MasterApp Xtra User Guide
[ doc last updated on March 22,1999 ]
Table of Contents
Sales and technical support
Credits
What MasterApp Xtra does
Methods at a glance
Getting started
Methods doc
Task
Thread
Module
Window
Launch
Launch Utilities
Input Simulation
Windows Registry
Miscellaneous
Encoding for special characters
Common
tasks
Open a web page
Check for existence of an app and launch
an installer
Go to a specific Acrobat page
Limitations
Version history
Standard legal
disclaimer
Sales and technical support
All licensing, pricing information and technical
inquiries regarding MasterApp Xtra should be directed to
updateStage which can be reached in the following ways:
sales e-mail: sales@updatestage.com
tech support e-mail: support@updatestage.com
phone: (781) 641-6043
fax: (781) 641-7068
website: www.updatestage.com
You can download a demonstration version of MasterApp Xtra
at:
ftp://ftp.shore.net/members/update/xtras/mappdemo.zip
You will also find demo movies of specific techniques and
helpful utility software in the Supporting Materials -> MasterApp section of the updateStage
downloads area.
Credits
MasterApp Xtra was developed by Glenn Picher of Dirigo
Multimedia
This user guide was written by Gretchen Macdowall, with
technical editing by Glenn Picher. Some portions are based on
product notes by Glenn Picher.
What MasterApp Xtra does
MasterApp Xtra launches, monitors and controls external
applications from Director. Director's "open doc with application"
command can also launch an external application but its
capabilities are limited in the following ways:
- On the Windows platform, with Director's open, you must
know the path to the application you want to launch. MasterApp
can use the system registry and other techniques to find the
application associated with a document type, rather than
requiring you to supply a path.
- On Windows, launching a document while an application is
running using Director's open command sometimes launches a
second copy of the application. MasterApp can load the
requested doc into the already-running application instead of
launching multiple copies of the same application.
- On the Mac you cannot use Lingo's open to open a document
with an application unless the application is the application
that created it. MasterApp's Launch family of methods will let
you open a doc into any application that knows how to handle
the document, regardless of the document's creator.
- Director's open does not give you any feedback if it fails.
MasterApp's launch methods return error codes, enabling you to
program alternatives and inform the user if the launch
fails.
- On the Mac, Lingo's open does not open a document if its
application is already running. MasterApp can.
MasterApp also returns information about open tasks and windows
on the system and gives you some control over applications outside
of Director. You can use MasterApp, for instance, to wait until
one external installer app has finished before launching the next
one, or to configure an app to a particular window size or
position
MasterApp offers more specific control over external apps by
enabling you to send simulated user mouse clicks and keystrokes to
another app. You can use it to auto-open a search dialog and
"type" in a search word, or to auto-dismiss a dialog that comes up
in the middle of a long process.
How MasterApp works with applications
The Task List and Window List are central to most of
MasterApp's operations. The Task List shows every executable
currently loaded into memory. The Task List includes DLL's,
Windows Explorer, and other system executables on the PC. On the
Mac it includes extensions and the Finder. Most tasks on the task
list have a corresponding window list. Neither a task nor its
windows have to be visible to the user to appear on the Task or
Window List.
The Task List
MasterApp's mappGetTaskList method returns the following
listings on the PC (example from Win98) and Mac, in string form,
one line per task, delimited by returns. Tabs and headings have
been inserted into the listings below for clarity. The actual task
names and ID's returned on any machine will vary depending on what
is currently running when mappGetTaskList is called.
Windows 95/98 Task List
Task Name Task ID Parent ID Instance ID Module ID
--------------------------------------------------------------------
KERNEL32.DLL, -3152041, -2124908191, -3152041, -3152041
MSGSRV32.EXE, -60485, -3152041, -60485, -60485
MPREXE.EXE, -53733, -60485, -53733, -53733
mmtask.tsk, -74137, -60485, -74137, -74137
ATMSG.EXE, -129373, -53733, -129373, -129373
EXPLORER.EXE, -79365, -60485, -79365, -79365
TASKMON.EXE, -119329, -79365, -119329, -119329
SYSTRAY.EXE, -118145, -79365, -118145, -118145
DIRECTOR.EXE, -134417, -79365, -134417, -134417
--------------------------------------------------------------------
Mac Task List
Task Name Task ID Parent ID Instance ID Module ID
----------------------------------------------------------------
FAXQueue Watcher, 32, 0, 32, 32
Finder, 33, 0, 33, 33
QuicKeys® Toolbox, 34, 33, 34, 34
File Sharing Exten, 35, 33, 35, 35
Stickies, 36, 33, 36, 36
VersaTile Pro 1.6.5, 37, 33, 37, 37
Notify Claris Email, 38, 0, 38, 38
Microsoft Word, 39, 33, 39, 39
Find File, 40, 33, 40, 40
Director 7, 41, 33, 41, 41
----------------------------------------------------------------
Task Name and Task ID
are by far the most-used pieces of information on the Task List.
Task Name is usually the name of the executable file, and Task ID
is a unique number that identifies that program, DLL or extension.
If you were to launch NOTEPAD on the PC twice, something you can't
do on the Mac, the two running copies of NOTEPAD would both appear
on the list on separate lines with the same Task Name but
different Task ID's.
Parent ID is the Task ID of the task that
launched the current task. In the listings you will notice that
apps launched by the user in Explorer or Finder have the Explorer
or Finder's Task ID for their parent. If you use MasterApp to
launch another app from your projector, the launched app will have
the projector's Task ID for its Parent ID. Windows NT is the one
exception - Parent ID is always 0 under that OS.
Instance ID and
Module ID only apply in the Windows 3.1 environment. Under 32-bit
Windows and on the Mac, Instance and Module ID aren't used and
will always be the same as Task ID. It is the rare Director
application these days that would need to bother with either
Module ID or Instance ID, although some of the Module
methods return unique information about the executable name
and its path that you may find useful under those OS's.
Module ID identifies one application or DLL loaded into Win 3.1
memory. What appear to be two launched copies of NOTEPAD.EXE
actually share the same code module loaded into memory and have
the same Module ID. Instance ID is unique and identifies each
separately running instance of a particular module. Two launched
copies of NOTEPAD.EXE on Win 3.1 would have different instance
ID's.
Window list
After an application has been launched, most MasterApp activity
to control it consists of performing various operations on its
windows, such as resizing, minimizing or sending simulated user
input to them. All MasterApp methods involving windows require a
Window ID to identify which window to operate on. The following
example window lists were built using MasterApp's mappGetTaskWindowList
method to return a list of the application's main windows and then
the mappGetChildWindowList
method to retrieve the children of each main window:
PC Window List for NOTEPAD.EXE
Window Name Window ID Parent Window ID Has Children Window Type
----------------------------------------------------------------------------
Untitled - Notepad, 2128, 0, 1, Notepad
, 2132, 2128, 0, Edit
----------------------------------------------------------------------------
Mac Window List for the System's Find File Utility
Window Name Window ID Parent Window ID Has Children Window Type
----------------------------------------------------------------------------
Find File, 32391888, 0, 1, 32135064
, 32134888, 32391888, 0, 0
, 32134920, 32391888, 0, 1
, 32134948, 32391888, 0, 0
Fewer Choices, 32134964, 32391888, 0, 0
More Choices, 32134980, 32391888, 0, 0
Find, 32135060, 32391888, 0, 0
----------------------------------------------------------------------------------------------------------
Document and application windows as we think of them are
actually comprised of many child "windows" by the Microsoft
Windows definition. Each button, text field or other widget on
what we think of as a window is considered a child "window" of the
containing parent window by the system. The Macintosh system does
not work quite the same way, but Mac MasterApp uses the
parent/child metaphor there as well, to ease cross-platform
scripting.
Not all windows, as you can see from the listings, have names,
and Mac window types have numbers rather than names. Some
invisible system elements are considered "windows".
Main windows usually have a Window Name
but their children don't always. In the examples above, Notepad's
main document window has a name, but the child window for text
entry does not. In the Mac example, the three buttons on the main
Find File window have names, but the 3 drop down pick lists do
not.
Each window has a Window ID that is unique
across applications. The component "window" widgets of a window
such as editable fields or buttons are child windows, which belong
to a Parent Window. In the examples above the window widgets for a
window all show the same Parent Window
ID. The corresponding property, Has
Children, is true for the parent windows and false for the window
widgets in the examples above. It is possible and common on Win to
have a window hierarchy within an application's Window List where
child windows have children of their own. On the Mac, there is
only one level. A parent window can have children ( controls ) but
those children cannot have children of their own.
Window Type is a much more useful
property on Win than on the Mac because on Win the window type is
a string. On Win the "Edit" window type is significant because it
tells you that the window widget accepts text input from the user.
These are the widgets to target when you want to send simulated
"typed" input from the user. For instance, you might want to open
a Find dialog and "type" in the search word to conduct a find in
another application from Lingo.
On Mac the types are numbers, which don't tell you much.
However, windows of a similar kind within an application usually
have the same window type. That might help you, for instance, to
identify all of an application's open document windows.
Much of the coding work in MasterApp involves iterating through
the task list at runtime looking for the task you are interested
in by name, then iterating once more through its main windows and
their child windows to find the window you want to control. Since
task ID's and window ID's will be different every time your app
runs, you must target windows by some characteristic that won't
change, such as their name or their window type. Here is a short
example, that finds Notepad's main document window, which has a
unique window type of "Notepad" :
on findNotepadTaskID
set taskList = mappGetTaskList()
set taskID = 0
set lookForTask = "NOTEPAD.EXE"
set the itemDelimiter = ","
set li = the number of lines of taskList
repeat with x = 1 to li
set taskName = item 1 of line x of taskList
if taskName = lookForTask then
set taskID = value(item 2 of line x of taskList)
-- current line looks like:
-- NOTEPAD.EXE,-134417,-79365,-134417,-134417
exit repeat
end if
end repeat
if taskID <> 0 then findMainDocWindow(taskID)
end
on findMainDocWindow taskID
set windowList = mappGetTaskWindowList(taskID)
set windowID = 0
set li = the number of lines of windowList
repeat with x = 1 to li
set windowType = item 5 of line x of windowList
if windowType = "Notepad" then
set windowID = value(item 2 of line x of windowList)
-- current line looks like:
-- ,2132,2128,0,Edit
end if
end repeat
put "Main doc window ID is: " & windowID
end
Note: It is possible for a task name or window name to contain
a comma. The code above assumes that there will only be 5 items
per line for clarity. It is actually safer to check the number of
items per line and concatenate the items at the beginning that
make up the name if you find more than 5.
Methods at a glance
|
Method and arguments
|
Purpose
|
|
register ( xtra "MasterApp",
regCodeString )
|
Prevents the demo dialog from coming up after
purchase.
|
|
Task Methods
|
|
mappGetTaskList ( )
|
Returns a list of the task names and ID's currently
running on the system
|
|
mappGetTaskIDs ( )
|
Returns a list of the task ID's currently running on
the system
|
|
mappTaskName (
taskIDNum)
|
Returns the name of the task corresponding to the
specified taskID
|
|
mappTaskParent (
taskIDNum)
|
Returns the name of the task corresponding to the
specified taskID
|
|
mappTaskInstance (
taskIDNum)
|
Returns the instance ID of the parent task
corresponding to the specified task
|
|
mappTaskModule (
taskIDNum)
|
Returns the module ID from which the specified task ID
was started
|
|
mappGetTaskWindowList
( taskIDNum)
|
Returns a list of the top-level window names and ID's
belonging to the specified task
|
|
mappGetTaskWindowIDs
( taskIDNum)
|
Returns a list of the top-level window ID's belonging
to the specified task
|
|
mappGetWindowTask (
windowIDNum)
|
Returns the taskID of the task owning the specified
window
|
|
mappRudeQuitTask (
taskIDNum, exitValueNum )
|
Unloads the specified task from memory.
|
|
mappTaskIsRunning (
taskIDNum)
|
Returns 0 if the specified task is not running
|
|
mappFeedTimeSlice (
taskIDNum)
|
Gives the specified task processing time
|
|
mappFeedGenericTimeSlice
( )
|
Forces Director to cede processing time to the system
and other running tasks
|
|
mappHostAppTask ( )
|
Returns the task ID of the program that MasterApp is
running in
|
|
mappDirectorTask (
)
|
Synonym of mappHostAppTask
|
|
mappAuthorwareTask (
)
|
Synonym of mappHostAppTask
|
|
mappTaskToFront (
taskIDNum )
|
Moves the specified task's windows to the front
|
|
mappGetTaskOrder (
)
|
Returns the task ID's of tasks with visible windows in
front to back order
|
|
Thread Methods
|
|
mappGetThreadList (
)
|
Returns a list of currently running thread ID's and
their parent ID's
|
|
mappGetTaskThreads (
taskIDNum)
|
Returns a list of thread ID's corresponding to the
specified task
|
|
mappGetThreadWindowList
( threadIDNum)
|
Returns a list of window names and window ID's owned
by the specified thread
|
|
mappGetThreadWindowIDs
( threadIDNum)
|
Returns a list of window ID's owned by the specified
thread
|
|
Module Methods
|
|
mappGetModuleList (
)
|
Returns a list of the module names and module ID's of
all modules currently running on the system
|
|
mappGetModuleIDs (
)
|
Returns a list of the module ID's of all modules
currently running on the system
|
|
mappModuleTask (
moduleIDNum)
|
Returns the first taskID started from the specified
module
|
|
mappModuleFileName (
moduleIDNum)
|
Returns the taskID corresponding to the specified
module
|
|
mappHostAppFilename
( )
|
Returns the filename of the executable MasterApp is
running from
|
|
mappDirectorFilename
( )
|
Returns the filename of Director authoring or the
Director projector MasterApp is running from
|
|
mappAuthorwareFilename
( )
|
Returns the filename of Authorware authoring or the
Authorware executable MasterApp is running from
|
|
mappModuleName (
moduleIDNum)
|
Returns the module name of the specified module
|
|
mappModuleIsRunning
( moduleIDNum)
|
Returns TRUE if the specified module ID is still
running
|
|
mappUnloadModule (
moduleIDNum, appOrDllString)
|
Unloads the specified module from memory
|
|
mappHostAppModule (
)
|
Returns the module ID of the executable MasterApp is
running from
|
|
mappDirectorModule (
)
|
Synonym of mappHostAppModule
|
|
mappAuthorwareModule
( )
|
Synonym of mappHostAppModule
|
|
Window Methods
|
|
mappGetParentWindowList
()
|
Returns a list of all parent window names and ID's,
generally in front to back order
|
|
mappGetParentWindowIDs
()
|
Returns a list of all parent window ID's
|
|
mappGetChildWindowList
( windowIDNum)
|
Returns a list of all child window names and ID's
owned by the specified window
|
|
mappGetChildWindowIDs
( windowIDNum)
|
Returns a list of all child window ID's owned by the
specified window
|
|
mappWindowParent (
windowIDNum)
|
Returns the window ID of the parent window for the
specified window
|
|
mappGetWindowParent
( windowIDNum)
|
Returns the window ID of the parent window for the
specified window
|
|
mappSetWindowParent
( windowIDNum, newParentWindowIDNum )
|
Assigns the specified parent ID to the specified
window
|
|
mappGetHighestWindowParent
( windowIDNum)
|
Returns the window ID of the parent at the topmost
level of the window hierarchy for the specified
window
|
|
mappWindowName (
windowIDNum)
|
Returns the name of the specified window
|
|
mappGetWindowName (
windowIDNum)
|
Returns the name of the specified window
|
|
mappSetWindowName (
windowIDNum, newNameString )
|
Assigns the specified name to the specified window
|
|
mappWindowHasChildren
( windowIDNum)
|
Returns TRUE if the specified window has any child
windows
|
|
mappWindowType (
windowIDNum)
|
Returns the window type of the specified window
|
|
mappGetWindowType (
windowIDNum)
|
Returns the window type of the specified window
|
|
mappWindowIsVisible
( windowIDNum)
|
Returns TRUE if the specified window is visible
|
|
mappFindWindow (
windowName, windowType )
|
Returns the window ID of the first window found
matching the specified name and type.
|
|
mappGetActiveWindow
( )
|
Returns the window ID of the currently active
window
|
|
mappSetActiveWindow
( windowIDNum)
|
Makes the specified window the currently active
window
|
|
mappGetForegroundWindow
( )
|
Returns the window ID of the current foreground
window
|
|
mappSetForegroundWindow
( windowIDNum)
|
Makes the specified window the foreground window
|
|
mappGetKeyboardInputWindow
( )
|
Returns the window ID of the window currently
receiving keyboard input
|
|
mappSetKeyboardInputWindow
( windowIDNum)
|
Makes the specified window the window that will
receive keyboard input
|
|
mappCaptureMouseInput
( windowIDNum)
|
Directs mouse clicks to the specified window
|
|
mappReleaseMouseInput
( )
|
Directs mouse clicks to the window they were going to
before mappCaptureMouseInput was used.
|
|
mappGetParentWindowTopChild
( windowIDNum)
|
Returns the topmost child window ID of the specified
parent window
|
|
mappGetDesktopWindow
( )
|
Returns the window ID of the desktop window
|
|
mappGetWindowOutsideRect
( windowIDNum)
|
Returns the 4 coordinates of the supplied window ID's
outside rect
|
|
mappGetWindowInsideRect
( windowIDNum)
|
Returns the 4 coordinates of the supplied window ID's
content area - excludes the title bar and borders.
|
|
mappSetWindowOutsideRect
( windowIDNum, leftNum, topNum, rightNum, bottomNum )
|
Resizes the outside rect of the specified window ID to
the coordinates specified
|
|
mappSetWindowRect (
windowIDNum, leftNum, topNum, rightNum, bottomNum )
|
Resizes the content area rect - what is inside the
title bar and window borders - of the specified window
ID, to the coordinates specified
|
|
mappCloseWindow (
windowIDNum )
|
Closes the specified window
|
|
mappSetCloseBoxOffset
( horOffsetNum, verOffsetNum )
|
Sets the position of the close box used to calculate
where a simulated click is sent by mappCloseWindow
method
|
|
mappFindWindowPart (
xLocNum, yLocNum )
|
Returns the window part under the specified point for
any window owned by Director or Authorware
|
|
mappWindowExists (
windowIDNum )
|
Returns TRUE if the specified window still exists
|
|
mappWindowToFront (
windowIDNum )
|
Moves the specified window in front of all other
windows
|
|
mappWindowToBack (
windowIDNum )
|
Moves the specified window behind all other
windows
|
|
mappHideWindow (
windowIDNum )
|
Makes the specified window invisible
|
|
mappShowWindow (
windowIDNum )
|
Makes an invisible window visible
|
|
mappMinimizeWindow (
windowIDNum )
|
Minimizes the specified window to an icon, if
possible
|
|
mappRestoreWindow (
windowIDNum )
|
Restores an minimized window to its previous size and
location
|
|
mappMaximizeWindow (
windowIDNum )
|
Resizes a window to fill the screen, if possible
|
|
mappSetUserZoomOffset
( horPixelNum, verPixelNum )
|
Resets the position used to send a simulated click to
a window's zoom box with the mappMaximizeWindow
method.
|
|
mappSetStandardZoomOffset
( horPixelNum, verPixelNum )
|
Resets the position used to send a simulated click to
a window's zoom box with the mappMaximizeWindow
method.
|
|
mappDirectorStageWindow
( )
|
Returns the window ID of Director authoring or the
Director projector's stage
|
|
mappHostAppMainWindow
( )
|
Returns the window ID of the main window of the
program MasterApp is running in
|
|
mappDirectorMainWindow
( )
|
Synonym of mappHostAppMainWindow
|
|
mappAuthorwareMainWindow
( )
|
Synonym of mappHostAppMainWindow
|
|
mappAuthorwarePresentationWindow
( )
|
Returns the windowID of Authorware's presentation
window
|
|
mappKeepOnTop (
windowIDNum )
|
Makes the specified window float on top of other
windows
|
|
mappDontKeepOnTop (
windowIDNum )
|
Reverts the specified window to normal behavior after
mappKeepOnTop was used
|
|
Launch Methods
|
|
mappLaunch ( appPathString,
commandLineArgsString )
|
Launches the application at the specified path
|
|
mappLaunchButDontActivate
( appPathString, commandLineArgsString )
|
Launches the application at the specified path but
does not bring it to the front
|
|
mappLaunchHidden (
appPathString, commandLineArgsString )
|
Launches the application at the specified path
invisibly
|
|
mappLaunchMinimized
( appPathString, commandLineArgsString )
|
Launches the application at the specified path
iconized, if possible
|
|
mappLaunchMaximized
( appPathString, commandLineArgsString )
|
Launches the application at the specified path and
displays its main window full screen
|
|
Launch Utility
Methods
|
|
mappLocateExecutable
( filenameString )
|
Returns the path to the executable registered to
handle the document at the file path specified
|
|
mappLocateAliases (
)
|
Allows mappLocateExecutable to return the path to an
alias
|
|
mappDontLocateAliases
( )
|
Prevents mappLocateExecutable from returning the path
to an alias
|
|
mappResolveAlias(
filePathString )
|
Returns the path to the actual file if passed a path
to an alias.
|
|
mappGetMenuBarHeight
( )
|
Returns the height in pixels of the menu bar.
|
|
mappSetMenuBarHeight
( pixelNumber )
|
Sets the menu bar to the specified height in
pixels
|
|
mappFixMenuBarOnLaunch
( )
|
Allows the menu bar height for applications launched
by MasterApp commands to be set by MasterApp
|
|
mappDontFixMenuBarOnLaunch
( )
|
Prevents MasterApp from setting the menu bar height
for applications launched by MasterApp
|
|
mappFixMenuBarHeight
( pixelNumber )
|
Sets the menu bar height in pixels used if mappFixMenuBarOnLaunch
has turned menu bar fixing on for launched apps
|
|
mappGetSystemScript
( )
|
Returns the system script number
|
|
mappGetSystemRegion
( )
|
Returns the system region number
|
|
mappGetShortFileName
( filepathString )
|
Returns the specified file path converted to DOS 8.3
format
|
|
mappGetLongFileName
( filepathString )
|
Returns the specified DOS file path converted to long
(Win 95 and later) format
|
|
mappOpenDocument (
docpathString )
|
Opens the document at the specified file path with the
application registered to handle it
|
|
mappPrintDocument (
docpathString )
|
Prints the document at the specified file path with
the application registered to handle it
|
|
mappInstanceTask (
instanceIDNum )
|
Returns the taskID corresponding to the specified
instanceID
|
|
mappInstanceIsRunning
( instanceIDNum )
|
Returns TRUE if the specified instance is still
running
|
|
mappUnloadInstance (
instanceIDNum , appOrDllString)
|
Unloads the specified instance from memory
|
|
Input Simulation
Methods
|
|
mappFakeMouseClick (
windowIDNum , horPointNum, verPointNum )
|
Simulates a user mouse click in the specified window
at the specified location
|
|
mappFakeMouseClickWait
( windowIDNum , horPointNum, verPointNum )
|
Simulates a user mouse click in the specified window
at the specified location and waits until the receiving
application processes the mouse click
|
|
mappFakeMouseDrag (
windowIDNum, fromHorNum, fromVerNum, toHorNum,
toVerNum)
|
Simulates a user mouse drag in the specified window,
from the start coords to the end coords specified.
|
|
mappFakeCharacter (
windowIDNum , charString )
|
Simulates the user typing an ASCII character in the
specified window
|
|
mappFakeCharacterWait
( windowIDNum , charString )
|
Simulates the user typing an ASCII character in the
specified window and waits until the receiving
application processes the character
|
|
mappFakeCharCode (
windowIDNum, charNum, codeNum )
|
Simulates the user typing a control character
combination such as Ctrl-C in the specified window
|
|
mappFakeCharCodeWait
( windowIDNum, charNum, codeNum )
|
Simulates the user typing a control character
combination such as Ctrl-C in the specified window and
waits until the receiving application processes the
control code
|
|
mappShowMenu ( windowIDNum
)
|
Targets the menu of the specified window for simulated
input
|
|
mappShowMenuWait (
windowIDNum )
|
Targets the menu of the specified window for simulated
input and waits until the receiving window processes the
request
|
|
mappAnyWindowAtPoint
( horPointNum, verPointNum )
|
Returns the windowID of the frontmost window under the
specified point
|
|
mappChildWindowAtPoint
( windowIDNum , horPointNum, verPointNum )
|
Returns the windowID of the frontmost child window
under the specified point of the specified parent
window
|
|
Windows Registry
Methods
|
|
mappGetWindowsRegistry
( baseString, keyString, valueString )
|
Returns the registry value at the specified
location
|
|
mappSetWindowsRegistry
( baseString, keyString, valueString, dataAnytype )
|
Sets the registry value at the specified location
|
|
mappGetWindowsRegistryEntries
( baseString, keyString )
|
Returns the list of registry subkeys and their values
under the specified key
|
|
mappGetWindowsRegistryKeys
( baseString, keyString )
|
Returns the list of registry subkeys under the
specified key
|
|
mappGetWindowsRegistryValues
( baseString, keyString )
|
Returns the list of registry values under the
specified key
|
|
mappGetWindowsRegistryEntryType
( baseString, keyString, valueString )
|
Returns the type of data stored at the specified
location
|
|
mappDeleteWindowsRegistry
( baseString, keyString, valueString )
|
Deletes the entry at the specified location
|
|
Miscellaneous Methods
|
|
mappGetDefaultPrinter
( )
|
Returns the name of the default printer
|
|
mappSetDefaultPrinter
( printerString )
|
Sets the default printer to the specified printer
name
|
|
mappGetInstalledPrinters
( )
|
Returns a list of all of the installed printer
names
|
|
mappWindowsFlavor (
)
|
Returns the type of Windows operating system - either
"win95" or "winNT"
|
|
mappDontUseLayerManager
( )
|
Turns use of the Layer Manager off
|
|
mappUseLayerManager
( )
|
Turns use of the Layer Manager on
|
|
mappGetSystemVersion
( )
|
Returns a string containing the Mac system
version.
|
Getting started
There are 3 versions of MasterApp covering the various
platforms:
|
Filename
|
Platform
|
|
MasterApp Xtra
|
Mac
|
|
MasterApp.x32
|
32-bit Windows (Windows 95,98,NT)
|
|
MastrApp.DLL
|
16- bit Windows (Windows 3.1)
|
MastrApp.DLL, for Windows 3.1, is an XObject. This
documentation covers the PC and Mac Xtras only. There is a text
document inside the XObject download that lists the available
methods for the XObject and their syntax. You may still find this
document helpful for getting a better idea of what each method
does. The Win XObject was the first version of MasterApp so the
Xtra's methods are a superset of the XObject's. See the Xtra
and XObject Primer for general information on how to
instantiate an XObject and how to call its methods.
In authoring, place the correct MasterApp Xtra for your
authoring platform in Director or Authorware's Xtras folder. For
delivery with your projector or runtime Authorware app, place the
correct MasterApp Xtra for your projector type in the Xtras folder
next to your projector/Authorware runtime app.
Director users can opt to include Xtras internally in the
projector instead. To include MasterApp internally, do Modify
-> Movie -> Xtras and manually add MasterApp to the movie's
Xtras list before making the projector. There is more information
on the pros and cons of including Xtras internally or externally
in the Xtra
and XObject Primer. Support recommendation? Use an external
Xtras folder.
Ignore the blue section if you are working with a demo version
of MasterApp Xtra
If you have purchased the MasterApp Xtra
you received a registration number and a registered copy of the
Xtra. Replace the old demo versions of the files with your
registered versions. The registered version does not display an
unregistered warning dialog when it starts up, but it will not let
you call any methods until you first use the register method. Call
the register method like so:
Director
register(xtra
"MasterApp","48dkd2929")
-- your registration number is the second
parameter
Authorware
var :=
CallParentObject("MasterApp","register","38dk22")
-- your registration number is the third
parameter
All of MasterApp's methods are global. That means that you do
not need to use a "new" call to make an instance of the Xtra. All
methods are available to you as soon as the Xtra loads. In
Authorware, you can get a listing of the available methods by
choosing Window -> Function. The methods appear under the
category "Xtra MasterApp".
Director is not set up by default to continue running after it
launches another application. You must turn the "Animate in
background" option on both in Director's authoring environment and
in a projector. Otherwise in Director authoring the movie will
stop running as soon as you launch an app, and a projector with
the option off will pause while the launched app is open. The
"Animate in background" option is in Director authoring's
Preferences. It is also under Options when you create a
projector.
Methods doc
register ( xtra
"MasterApp", registrationCodeString)
The demo version of MasterApp Xtra will display a
trial-version alert the first time you use a
method. If you have purchased the MasterApp
Xtra you received a registration number and a registered copy of
the Xtra. Replace the old demo versions of the files with your
registered versions. The registered version does not display an
unregistered warning alert when it starts up, but it will not let
you call any methods until you first use the register method. Call
the register method like so:
register(xtra
"MasterApp","48dkd2929")
-- your registration number is the second
parameter
If you have problems registering the MasterApp Xtra, please
check the following:
Example:
register(xtra
"MasterApp","48dkd2929")
A task is a process currently
running on the system. Most tasks that you will want to use
MasterApp to monitor will be user applications, but a task can
also be a process that loaded at startup and is running invisibly.
Both user applications and tasks normally invisible to the user
will appear on the system task list returned by MasterApp.
mappGetTaskList ()
Returns: string containing a list of the tasks
currently running on the system, one per line. Return value may
contain encoding for special characters.
Provides information about currently running tasks. Each line
represents one task and provides the following 5 items, separated
by commas, per task line:
taskName, taskID,
parentTaskID, instanceID,
moduleID
Here is what a typical return from mappGetTaskList looks
like:
put mappGetTaskList()
-- "Control Strip Extension,32,0,32,32
FAXQueue Watcher,33,0,33,33
Folder Actions,34,0,34,34
OSA Menu,35,0,35,35
Time Synchronizer,36,0,36,36
Finder,37,0,37,37
File Sharing Extension,38,37,38,38
Stickies,39,37,39,39
VersaTile Pro 1.6.5,40,37,40,40
BBEdit 4.0,41,37,41,41
Jade FAT,42,37,42,42
Notify Claris Emailer,43,0,43,43
Claris Home Page,44,37,44,44
Director 5.0.1,45,37,45,45"
Task ID's are always nonzero but their possible range varies
with the operating system. Task ID's are negative on Win 95,98 and
positive numbers on WinNT. On the PC, Task ID's are assigned by
the system. It is possible, on the PC, for a taskID that was
assigned to a process that has terminated, to be reassigned to a
new process. Under WinNT, parentTaskID always returns 0.
On the Mac, taskID's are positive integers, starting at 32,
created by MasterApp. A taskID of 31 or less on the Mac indicates
an error. TaskID's are not reused on the Mac - the taskID formerly
used by a terminated process will not get assigned to a new
process. On the Mac, all tasks have a parentTaskID, except for the
Finder which has a parentTaskID of 0.
InstanceID and moduleID are relevant only
under Win3.1. On 32-bit OS's and on the Mac, instanceID and
moduleID are the same as taskID.
It is possible for a task name to contain a comma. If there are
more than 5 items in a line your code should concatenate the items
at the beginning to retrieve the full task name.
Example:
on findTaskInList nameString
-- Cycle through task list and return the
-- entire information line for that task
-- from the task list
--
-- EX: set taskInfo = findTaskInList("DIRECTOR.EXE")
-- put taskInfo
-- "DIRECTOR.EXE,-1001019,-1000951,-1001019,-1001019"
--
set notFoundString = ""
set taskList = mappGetTaskList()
set cnt = the number of lines in taskList
repeat with x = 1 to cnt
set oneTask = line x of taskList
if oneTask contains nameString then
return oneTask
end if
end repeat
return notFoundString
end
mappGetTaskIDs ()
Returns: a string containing the taskID's of all
currently running tasks
Returns a string of the taskID's of all currently running
tasks, all on one line, separated by spaces. Use 'word' to walk
through the results. This is a better method than mappGetTaskList
to use if you are looking for a specific taskID, because a
taskName containing a comma won't affect the position of the
results. Returns the frontmost task first.
Example:
on findMyKids parentID
-- Returns only taskID's launched by supplied parent ID
-- ID's returned in linear Lingo list
--
-- EX: set kidList = findMyKids(37)
-- put kidList
-- [38, 39, 40, 42, 43, 44]
--
set kidList = []
set tasks = mappGetTaskIDs()
set wds = the number of words of tasks
repeat with x = 1 to wds
set id = value(word x of tasks)
if launchedBy(parentID,id) then
append kidList,id
end if
end repeat
return kidList
end
on launchedBy parentID,childID
-- Returns TRUE if the supplied childID was started by
-- the supplied parent ID
--
-- EX: set childOf = launchedBy(35,54)
--
if mappTaskParent(childID) = parentID then
return TRUE
else
return FALSE
end if
end
mappTaskName ( taskIDNum)
taskIDNum: integer task ID obtained from another
method
Returns: task name corresponding to the taskID or string
beginning with "Error:"
Returns internal name for a taskID. Return value may contain
encoding for special characters. On the
Mac, if the task is an application, this is the same text that's
displayed on the applications pulldown menu. Use mappModuleFileName
to get the full filename of the task.
Example:
set taskName = mappTaskName(taskID)
mappTaskParent ( taskIDNum)
taskIDNum: integer task ID obtained from another
method
Returns: integer taskID of task's parent or 0
Returns the task's parent task ID.
Example:
on launchedBy parentID,childID
-- Returns TRUE if the supplied childID was started by
-- the supplied parent ID
--
-- EX: set childOf = launchedBy(35,54)
--
if mappTaskParent(childID) = parentID then
return TRUE
else
return FALSE
end if
end
mappTaskInstance ( taskIDNum)
taskIDNum: integer task ID obtained from another
method
Returns: integer instanceID associated with the task or
0 if there is no instanceID
Returns a task's instanceID. This is only relevant under Win
3.1 so the method only exists for compatibility with the XObject
version. On the Mac and 32-bit Windows systems, the taskID and
instanceID are the same. So on those systems the method returns
the same ID provided, or 0 if the taskID is no longer valid.
Example:
set instanceID = mappTaskInstance(taskID)
mappTaskModule ( taskIDNum)
taskIDNum: integer task ID obtained from another
method
Returns: integer moduleID associated with the task or 0
if there is no moduleID
Returns a task's moduleID. This is only relevant under Win 3.1
so the method only exists for compatibility with the XObject
version. On the Mac and 32-bit Windows systems, the taskID and
moduleID are the same. So on those systems the method returns the
same ID provided, or 0 if the taskID is no longer valid.
Example:
set moduleID = mappTaskModule(taskID)
mappTaskEvents ( taskIDNum)
taskIDNum: integer task ID obtained from another
method
Returns: integer number of events waiting to be
processed by the specified task, or -1 if taskID is invalid
Only relevant on Win 3.1 and retained for backwards
compatibility with XObject. Returns the number of events waiting
for the task to process. On 32-bit Win systems it always returns
0. On the Mac, it always returns 0 for tasks other than the
Director task itself, and never returns more than 1.
Example:
set waitingEvents = mappTaskEvents(taskID)
mappGetTaskWindowList (
taskIDNum)
taskIDNum: integer task ID obtained from another
method
Returns: string list of all top-level windows owned by
the task or string beginning with "Error:"
Returns a list of all windows owned by the task, one per line,
in the format:
windowName,
windowID,
parentWindowID,
hasChildren,
windowType
Here is what a typical return from mappGetTaskWindowList looks
like for the Director task on the Mac:
put mappgettaskwindowlist(45)
-- ",13132032,0,0,26844720
Control Panel,13131856,0,0,26800756
Tooltip,13131328,0,0,26787640
Toolbar,13131152,0,0,26799360
Message,13129760,0,1,26836488
Stage,13129936,0,0,26836712
Internal Cast,13132208,0,1,26839652
Untitled Score,13131680,0,1,26808976
Paint,13131504,0,1,26786832
Color Palettes,13130976,0,1,12927888"
On the Mac, parentWindowID is always 0 for windows returned by
this method because there is no main application window containing
all of the app's other windows as there is on Win. A windowName
may contain commas, so mappGetTaskWindowIDs is a more bulletproof
method of identifying all windows.Return value may contain
encoding for special characters.
On Windows, the windows in the list are returned in
front-to-back draw order. On the Mac, use mappGetTaskOrder
to determine the front-to-back draw order of applications.
Example:
on getWindowInList nameString,taskID
-- Cycle through window list and return the
-- entire information line for that window
-- from the task's window list
--
-- EX: set winInfo = getWindowInList("Tooltip",45)
-- put winInfo
-- "Tooltip,13131328,0,0,26787640"
--
set notFoundString = ""
set windowList = getTaskWindowList(taskID)
set cnt = the number of lines in windowList
repeat with x = 1 to cnt
set oneWin = line x of windowList
if oneWin contains nameString then
return oneWin
end if
end repeat
return notFoundString
end
mappGetTaskWindowIDs (
taskIDNum)
taskIDNum: integer task ID obtained from another
method
Returns: string containing a list of window ID's owned
by the specified task or string beginning with "Error:"
Returns a string containing the windowID's of all of the task's
windows, on one line,separated by spaces. Use 'word' to walk
through the results.
Example:
on taskWindowOfNameExists wName,taskID
-- Returns TRUE if the given window name still
-- exists for the given task
--
-- EX: set exists = taskWindowOfNameExists("Print",786)
--
set windowList = mappGetTaskWindowIDs(taskID)
set numWins = the number of words of windowList
repeat with x = 1 to numWins
set win = value(word x of windowList)
if mappGetWindowName(win) = wName then
return TRUE
end if
end repeat
-- window not found
return FALSE
end
mappGetWindowTask (
windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: integer taskID for task that owns the specified
window or 0 if windowID is invalid
Returns the task that owns a given window.
Example:
set belongsToTask = mappGetWindowTask(5403)
mappRudeQuitTask integer (
taskIDNum, exitValueNum )
taskIDNum: integer task ID obtained from another
method
exitValueNum: integer status value that the terminated task
should pass back to Windows, which in turn, passes it back to the
program that launched the program that is quitting. Use 0 for this
param unless the task is a custom app that requires
another value.
Returns: Returns 0 if the program's already quit, -4 if
it's still running, -2 if taskID is invalid. It's not unusual to
see -4 as a result. On Win32, -4 is *always* the result.
Forces a task to quit. This is a reliable way to quit
applications on the Mac, but not on Win. On Win you should use
mappCloseWindow on the application's main window instead, which is
equivalent to the user quitting the app. Use mappFindWindow
to get the windowID. RudeQuit on Win unceremoniously unloads the
task from memory without giving it any opportunity to clean up
after itself. mappCloseWindow is like opening the door and waving
good-bye to a departing guest - mappRudeQuitTask is like shooting
him in the head. However, some nonstandard PC apps may not respond
to mappCloseWindow or may not have a main window to close. In that
case, rudeQuit may be necessary.
This method isn't all that rude on the Mac. It sends a System-7
standard 'quit' AppleEvent or simulates a Quit menu choice, for
pre-System-7 software. AppleScript is *not* required to be
installed to send AppleEvents. On the Mac, exitValue is
ignored.
Because this is the equivalent of a Quit menu choice on the Mac
by the user, the app you're trying to quit may display a 'don't
save'/'cancel'/'save' dialog. You can dismiss it by sending a
simulated mouse click to the appropriate button.
On both platforms, you may need to feed
the quitting process some timeslices to allow it enough time
to quit. This is demonstrated in the code example.
The exit value parameter exists for
historical reasons. Passing any value but 0 would be useful only
in a custom-written application that needs to have specific
information about why a program quit. Very few Windows
applications are designed to get their information from exit
values when a program quits, since Windows programs are designed
to multitask and not run sequentially. But this is a technique
that has historical precedent in MS-DOS programs and more
generally ANSI compliant programs, and so was preserved in Windows
3.1 for the convenience of portability. Passing 0 for this
parameter is generally the thing to do.
Example:
on quitTask taskID
mappRudeQuitTask(taskID,0)
mappTaskToFront(taskID)
set limit = the timer + (5 * 60)
repeat while the timer < limit and mappTaskIsRunning(taskID)
mappFeedGenericTimeSlice
end repeat
end
mappTaskIsRunning ( taskIDNum)
taskIDNum: integer task ID obtained from another
method
Returns: 0 if the specified task is not running. On Mac
returns 1 if the task is running. On Win returns the taskID if the
task is running.
This method is useful for determining if a task you send a quit
to is still running. It is also useful as a check before using a
method that makes use of a taskID that you obtained previously.
Check for a non-zero value in code that should work cross
platform.
Example:
if mappTaskIsRunning(taskID) <> 0 then
set winList = mappGetTaskWindowList(taskID)
else
put "Task is no longer running."
end if
mappFeedTimeSlice ( taskIDNum)
taskIDNum: integer task ID obtained from another
method
Returns: 0:no error, -1:invalid task ID, -2 task was
already receiving timeslices
Mac, Win 3.1 method only. This method is a synonym for
mappFeedGenericTimeSlice on 32-bit Win systems.
Wakes the specified task up, and gives it some processing time.
This method, or mappFeedGenericTimeSlice
is most useful in conjunction with other operations that send
messages to a window that the application may need time to
process. For instance, if you find that mappCloseWindow is not
working with a particular application you can feed the application
some processing time to execute the command after sending the
closeWindow message. See example.
The duration of the timeslice varies depending on the operating
system and what other tasks are running. On the Mac, this method
does not necessarily insure that the indicated task will get
processing time immediately (due to differences in event
processing architecture), but it does make the task get processing
time as soon as possible. This method may be necessary for apps to
process messages. It is especially useful within a Lingo repeat
loop, which normally monopolizes all timeslices.
Possible side effect: the Director task's windows may not be
properly updated if this method is used within a long repeat loop
and the user switches applications. In other words, if you starve
the Director application of processing time by feeding it all to
other applications, Director's own windows will not be able to
update. You cannot use this method to feed the Director task
itself more timeslices. You must use
Lingo for that.
On Win32, the taskID is ignored. This method has the same
effect as a generic time slice.
Example:
-- Insures that windowToFront and windowClose messages
-- have enough time to process
--
-- EX: waitForClose(89477,43)
--
on waitForClose windowID,taskID
mappWindowToFront(windowID)
mappFeedTimeSlice(taskID)
mappCloseWindow(windowID)
set limit = the timer + (5 * 60)
repeat while the timer < limit
set ls = " " & mappGetTaskWindowIDs(taskID) & " "
if not(ls contains " " & windowID & " ") then
exit repeat
end if
mappFeedTimeSlice(taskID)
end repeat
end
mappFeedGenericTimeSlice
Return: No return
Makes the Director task cede processor time to the system so
that other tasks can run. Differs from mappFeedTimeSlice
in that the system decides which process will get the ceded time.
Useful within Lingo repeat loops, which normally monopolize all
timeslices. No return value.
Possible side effect: the Director task's windows may not be
properly updated if this method is used within a long repeat loop
and the user switches applications. In other words, if you starve
the Director application of processing time by feeding it all to
other applications, Director's own windows will not be able to
update. You cannot use this method to feed the Director task
itself more timeslices. You must use
Lingo for that.
Example:
on longProcess
set onRec = 1
repeat while onRec <= numRecs
-- fictional process that takes a long time
rewriteRecord(onRec)
-- Give other apps some processing time
-- between each record
mappFeedGenericTimeSlice
set onRec = onRec + 1
end repeat
end
mappHostAppTask ()
Returns: the taskID of the app hosting MasterApp
Xtra.
Returns the taskID of either the Director or Authorware
application if running in authoring. Returns the taskID of either
the Director projector or the Authorware standalone at
runtime.
Example:
set hostAppID = mappHostAppTask ()
mappDirectorTask ()
Returns: the taskID of the app hosting MasterApp
Xtra.
Returns the taskID of the Director application if running in
authoring or returns the taskID of the Director projector. Synonym
of mappHostAppTask.
Example:
set directorID = mappDirectorTask ()
mappAuthorwareTask ()
Returns: the taskID of the app hosting MasterApp
Xtra.
Authorware-only method. Returns the taskID of the Authorware
application if running in authoring or returns the taskID of the
Authorware standalone at runtime. Synonym of mappHostAppTask.
Example:
authorwareID := mappAuthorwareTask()
mappTaskToFront ( taskIDNum )
Returns: 0 if successful or Mac
system error number
Mac-only method. Moves the task to the front. Does not exist on
Windows because of some fundamental differences between Mac and
Win in the way tasks are managed. No equivalent function in the
Windows API. Instead, use mappWindowToFront
on an application's main window, which you can identify from a
taskID with mappGetTaskWindowList
or mappGetTaskWindowIDs.
Example:
on moveItUp taskID
mappTaskToFront(taskID)
mappFeedTimeSlice(taskID)
end
mappGetTaskOrder ()
Returns: a string containing taskID's separated by
spaces, in front to back order
Lets you detect the front-to-back order of all visible
applications, even if they are not showing any windows. Reports
taskID's with visible windows, in front-to-back order. Note that
on 32-bit Win systems,Windows Explorer usually shows up first, due
to the Windows task bar.
Example:
on getFrontTaskID
return value(word 1 of mappGetTaskOrder())
end
Multithreading enables a process to
designate blocks of its code as threads that can run
simultaneously. Each process automatically starts off in one
thread, but can spawn other threads later on. A web browser, for
example, takes advantage of multithreading to download files while
it also continues to display new web pages.
The thread methods were included because
on Windows NT, 16-bit applications do not run as separate tasks.
They all run under one task - Windows on Windows (WOW) as multiple
threads. In order to distinguish one 16-bit running app from
another on NT, you must use the thread methods. All of the thread
methods only exist on the 32-bit Win platform.
mappGetThreadList ()
Returns: string list of all threads, one thread
per line in the following format
threadID, parentTaskID
32-bit Win method only. By combining this method with
mappGetThreadWindowList you can identify a 16-bit Win app running
under Windows NT so that you can send messages to or otherwise
control their windows.
Example:
set threadList = mappGetThreadList()
mappGetTaskThreads (
taskIDNum)
Returns: string containing threads ID's, separated
by spaces or string beginning with "Error:"
32-bit Win method only. Lists thread ID's owned by specified
task ID.
Example:
set taskThreads = mappGetTaskThreads(-5408342)
mappGetThreadWindowList (
threadIDNum)
Returns: string containing window information, one
line per window in the following format or string beginning with
"Error:"
windowName, windowID, parentWindowID, hasChildren, windowType
32-bit Win method only. Returns window information for windows
owned by the specified thread.
Example:
-- Returns the window ID for a window name
-- even if the window belongs to a 16-bit
-- app running on NT
--
-- EX: set foundID = findThreadWindow("Untitled")
--
on findThreadWindow windowName
set windowID = 0
set savDelim = the itemDelimiter
set the itemDelimiter = ","
set threadList = mappGetThreadList()
set lns = the number of lines of threadList
repeat with x = 1 to lns
if windowID > 0 then exit repeat
set threadID = value(item 1 of line x of threadList)
set windowList = mappGetThreadWindowList(threadID)
set wlns = the number of lines in windowList
if char 1 to 6 of windowList = "Error:" or windowList = "" then
next repeat
else
repeat with y = 1 to wlns
set oneWin = line y of windowList
if item 1 of oneWin = windowName then
set windowID = value(item 2 of oneWin)
exit repeat
end if
end repeat
end if
end repeat
set the itemDelimiter = savDelim
return windowID
end
mappGetThreadWindowIDs (
threadIDNum)
Returns: string containing list of window ID's
separated by spaces or string beginning with "Error:"
32-bit Win method only. Returns list of window ID's owned by
the specified thread.
Example:
set threadWins = mappGetThreadWindowIDs(-43728)
A module is an application or DLL loaded into Win 3.1
memory that can be reused. What appear to be two launched copies
of NOTEPAD.EXE actually share the same code module loaded into
memory and have the same Module ID. "Modules" do not exist in
either the 32-bit Windows environment or on the Mac. ModuleID is
the same as taskID on those OS's.
The module methods exist in the Win32 and Mac Xtras mostly for
backwards compatibility, although some methods return information,
such as the path to the executable or the executable file type and
creator that may be useful on those OS's.
mappGetModuleList ()
Returns: string of module information, one line
per module in the following format
moduleName, moduleID, moduleFileName
Returns a string of all currently loaded modules, one per line.
Return value may contain encoding for special
characters. Since moduleName or moduleFileName might contain
commas, mGetModuleIDs is a more bulletproof way of listing all
modules.
moduleName is the executable name on the PC. On the Mac,
it contains the executable's file type and creator. You can use
this information on Mac to identify a particular application even
if the application name itself varies from version to version or
because it has been localized for a particular language.
moduleID is the same as taskID on Win32 and Mac
platforms
moduleFileName is the full path to the executable on all
platforms except NT, where it only contains the executable file
name without the full path or extension.
Example:
Mac
put mappgetmodulelist()
-- "sdevappe,32,Macintosh HD:System Folder:Extensions:Control Strip Extension
FQWAappe,33,Macintosh HD:System Folder:Extensions:FAXQueue Watcher
ssrvappe,34,Macintosh HD:System Folder:Extensions:Folder Actions
osaMappe,35,Macintosh HD:System Folder:Extensions:OSA Menu
timsappe,36,Macintosh HD:System Folder:Extensions:Time Synchronizer
MACSFNDR,37,Macintosh HD:System Folder:Finder
notzAPPL,38,Macintosh HD:System Folder:Apple Menu Items:Stickies
1CLkAPPL,39,Big:Utilities:VersaTile:VersaTile Pro 1.6.5
MP02APPL,41,Big:Communications:Internet:Claris Emailer Folder:Claris Emailer Files:Notify Claris Emailer
BlWdAPPL,43,Big:HTML editors:Claris Home Page 3.0:Claris Home Page 3.0
MD95APPL,44,Big:Director 5:Director 5.0.1
R*chAPPL,45,Big:Text editors:BBEdit 4.0:BBEdit 4.0
hhggINIT,46,Macintosh HD:System Folder:Extensions:File Sharing Extension"
Win95
put mappgetmodulelist()
-- "KERNEL32.DLL,-3169757,C:\WINDOWS.95\SYSTEM\KERNEL32.DLL
MSGSRV32.EXE,-110801,C:\WINDOWS.95\SYSTEM\MSGSRV32.EXE
MPREXE.EXE,-106877,C:\WINDOWS.95\SYSTEM\MPREXE.EXE
mmtask.tsk,-74593,C:\WINDOWS.95\SYSTEM\mmtask.tsk
EXPLORER.EXE,-71037,C:\WINDOWS.95\EXPLORER.EXE
REMIND.EXE,-960833,C:\Tools_95\Register\REMIND.EXE
SYSTRAY.EXE,-959265,C:\WINDOWS.95\SYSTEM\SYSTRAY.EXE
LOADWC.EXE,-962933,C:\WINDOWS.95\SYSTEM\LOADWC.EXE
ATMSG.EXE,-950877,C:\MACLAN6\ATMSG.EXE
IMGICON.EXE,-82137,C:\TOOLS_95\IMGICON.EXE
IOWATCH.EXE,-980009,C:\TOOLS_95\IOWATCH.EXE
DDHELP.EXE,-1029093,C:\WINDOWS.95\SYSTEM\DDHELP.EXE
DIRECTOR.EXE,-949225,C:\PROGRAM FILES\MACROMEDIA\DIRECTOR 6\DIRECTOR.EXE
RSXTOOL.EXE,-1003845,C:\WINDOWS.95\SYSTEM\RSXTOOL.EXE"
mappGetModuleIDs ()
Returns: string of moduleID's separated by spaces
Returns a string of the moduleIDs of all running modules, on
one line,separated by spaces. Use 'word' to walk through the
results. On 32-bit Win and Mac this does the same thing as
mappGetTaskIDs
Example:
set moduleIDList = mappGetModuleIDs()
mappModuleTask ( moduleIDNum)
moduleIDNum: integer module ID obtained from
another method
Returns: integer task ID or 0
Returns the taskID of the specified moduleID. Since they are
both the same on Win32 and Mac, this is not a very useful method
on those platforms.
Example:
set taskID = mappModuleTask(-1029093)
mappModuleFileName (
moduleIDNum)
moduleIDNum: integer module ID obtained from
another method
Returns: string file path or string beginning with
"Error:"
Returns the full path to a task's application file on every
platform but Windows NT, where it only returns the file name
without the full path or extension. Since module ID and task ID
are the same on 32-bit Win and Mac, you can pass a task ID to it
on those platforms. Return value may contain encoding for
special characters.
Example:
set pathToApp = mappModuleFileName(-1029093)
mappHostAppFilename ()
Returns: string file path
Returns the full path to the application the Xtra is running
out of.
Example:
set pathToHost = mappHostAppFilename ()
mappDirectorFilename ()
Returns: string file path
Returns the full path to Director authoring or to the Director
projector. Synonym of mappHostAppFilename.
Return value may contain encoding for special
characters.
Example:
set pathToDirector = mappDirectorFilename ()
mappAuthorwareFilename ()
Returns: string file path
Authorware-only method. Returns the full path to Authorware
authoring or to the Authorware runtime application. Synonym of
mappHostAppFilename. Return
value may contain encoding for special
characters.
Example:
pathToAuthorware := mappAuthorwareFilename()
mappModuleName ( moduleIDNum)
moduleIDNum: integer module ID obtained from
another method
Returns: string containing module name or string
beginning with "Error:"
On the Mac, this is the app's creator and file type
signatures,returned as an 8-character string. You can use this
information on Mac to identify a particular application even if
the application name itself varies from version to version or
because it has been localized for a particular language. On Win32,
this is a synonym for task name.
Example:
set modName = mappModuleName(-1029093)
mappModuleIsRunning (
moduleIDNum)
moduleIDNum: integer module ID obtained from
another method
Returns: 0 if the module is no longer running. On Win
returns the moduleID if the module is running, on Mac returns 1 if
the moduleID is running.
On 32-bit Win and Mac, this is a synonym for mappTaskIsRunning.
For cross-platform check, check for non-zero value to see if
module is running.
Example:
if mappModuleIsRunning(moduleIDNum) then
mappUnloadModule(moduleIDNum)
end if
mappUnloadModule ( moduleIDNum)
moduleIDNum: integer module ID obtained from
another method
Returns: 0 if the program's already quit, -4 if it's
still running, -2 if taskID is invalid. It's not unusual to see -4
as a result. On Win32, -4 is *always* the result.
Forces a module to quit. On Win32 and Mac, this method is
synonymous with mappRudeQuitTask. Under Win3.1, unloading a module
will quit multiple instances using the module simultaneously.
Example:
mappUnloadModule(-1029093)
mappHostAppModule ()
Returns: integer module ID
Returns the module ID of the app out of which MasterApp Xtra is
running. On Win32 and Mac this method is synonymous with mappHostAppTask
Example:
set modID = mappHostAppModule ()
mappDirectorModule ()
Returns: integer module ID
Returns the module ID of the Director authoring app or
projector. On Win32 and Mac this method is synonymous with
mappDirectorTask
Example:
set modID = mappDirectorModule ()
mappAuthorwareModule ()
Returns: integer module ID
Authorware-only method. Returns the module ID of the Authorware
authoring app or runtime executable. On Win32 and Mac this method
is synonymous with mappAuthorwareTask
Example:
modID := mappAuthorwareModule ()
MasterApp's window methods return
information about a process's windows which you can use to
identify windows you want to send user input to, or otherwise
control. MasterApp's window manipulation methods interact directly
with system routines, which means that information that you pass
to MasterApp methods or that is returned to you from MasterApp
methods is not, for the most part, filtered. It is possible to
crash the system by passing an invalid value for windowID and it
is also possible to get some strange information back from the
system under certain conditions.
Passing windowID's
Although the methods that accept a window
ID contain some built-in error checking for invalid windows, do
not pass 0 for a window ID to any method that manipulates a
window. The Mac system can crash if passed a window ID of
0.
Parsing a returned window
list
A couple of factors affect the
information returned by mappGetParentWindowList
and mappGetChildWindowList.
First, windowName on Mac and both windowName and windowType on Win
are strings. It is possible for either windowName or windowType to
contain commas. That could cause code expecting to find another
item of information in a particular item position to return the
wrong item.
If you are cycling through a returned list looking for an exact
match on window name, to retrieve window ID, and the string you
are looking for does not contain commas, then it does not matter
if commas or control characters create bogus lines and items in
the window list. The name you are looking for will be in item 1 of
some line of the windowlist and the windowID will be in item 2 of
that line, even if some of the other lines are in disarray.
If you are looking for some other piece of information, such as
window type, or you are listing out all window names, rather than
looking for a specific one, you cannot rely on simple "item x of
line y" parsing to return the correct information. Instead you
should combine mappGetParentWindowIDs
or mappGetChildWindowIDs and
mappWindowName to extract the
information like so:
-- Returns the first window found of a
-- particular type. Pass a string for
-- window type on Mac and PC
--
-- EX: set id = findwindowtype("30195868")
--
on findWindowType theType
set windowID = 0
set origList = mappGetParentWindowList()
set winIDs = mappGetParentWindowIDs()
set winList = []
set ln = the number of lines in origList
-- Make a Lingo list containing lines of window list
repeat with x = 1 to ln
append winList,line x of origList
end repeat
set w = the number of words of winIDs
-- Cycle through window IDs and look for line that starts
-- with the windowname for that ID
repeat with x = 1 to w
if windowID <> 0 then exit repeat
set curid = value(word x of winIDs)
if curid <> 0 then
set curName = mappWindowName(curid)
set lenName = length(curName)
repeat with y = 1 to ln
set curWin = getAt(winList,y)
if char 1 to lenName of curWin = curName then
-- If the beginning of this line matches the
-- window name, then chop off the window name
-- and the 3 following items which always
-- contain valid numbers. What's left is
-- the window type
delete char 1 to lenName of curWin
delete item 1 to 4 of curWin
if curWin = theType then
set windowID = curid
exit repeat
end if
end if
end repeat
end if
end repeat
return windowID
end
mappGetParentWindowList
()
Returns: string containing window information, one
window per line in the following format
windowName,
windowID,
parentWindowID,
hasChildren,
windowType
Returns a string of all top-level windows owned by all tasks.
On Win, the windows are listed in front-to-back screen draw order,
though not all of the reported windows may be visible or
on-screen. The taskbar, or tool tip windows, are typically the
first windows listed on Win32 platforms. On Mac the windows are
generally returned in front-to-back task order with the windows of
the frontmost task first. Windows not connected to any task appear
at the end of the list. Hidden windows not seen by the user can
appear on this list.
Top-level windows always have parentID 0, but the data format
returned is the same data format returned by mappGetChildWindowList.
Because windowNames might contain commas, using mappGetParentWindowIDs
is more bulletproof.
Example:
-- Returns the windowID for the window name
-- you supply
--
-- EX: set winID = findAppWindow("Untitled")
on findAppMainWindow winName
-- Assumes the winName you're looking for does not itself
-- contain a comma
--
set foundWin = 0
set savDelim = the itemDelimiter
set the itemDelimiter = ","
set winList = mappgetparentwindowlist()
set lns = the number of lines of winList
repeat with x = 1 to lns
set oneWin = line x of winList
if item 1 of oneWin= winName then
set foundWin = value(item 2 of oneWin)
exit repeat
end if
end repeat
set the itemDelimiter = savDelim
return foundWin
end
mappGetParentWindowIDs ()
Returns: string containing window ID's separated
by spaces
Returns the windowID's of all top-level windows, on one
line,separated by spaces. Use 'word' to walk through the results.
On Windows, mappGetParentWindowIDs
returns results in front-to-back draw order. On Mac the windows
are generally returned in front-to-back task order with the
windows of the frontmost task first. Windows not connected to any
task appear at the end of the list. Hidden windows not seen by the
user can appear on this list.
Example:
set windIDList = mappGetParentWindowIDs()
mappGetChildWindowList (
windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: string containing window information, one line
per window in format or string beginning with "Error:"
windowName,
windowID,
parentWindowID,
hasChildren,
windowType
Returns a string of all child windows owned by the window.
Since windowName might contain commas, mappGetChildWindowIDs
is a more bulletproof way of listing all child windows. Return
value may contain encoding for special
characters.
Example:
set winList = mappGetChildWindowList(28029632)
mappGetChildWindowIDs(
windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: string containing window ID's separated by
spaces or string beginning with "Error:"
Returns a string of all child windows owned by the window, on
one line, separated by spaces. Use 'word' to walk though the
results.
Example:
set winIDList = mappGetChildWindowIDs(28029632)
mappWindowParent ( windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: integer window ID
Returns the windowID of the parent of the supplied window or 0
if it's a top-level window, or -1 if the supplied windowID can't
be found.
Example:
-- Returns TRUE if windowID is a child of the
-- window name supplied
--
-- EX: set rightParent = isChildOfParentNamed(13577236,"Message")
--
on isChildOfParentNamed windowID,parentNameLookingFor
set rightParent = FALSE
set parentWin = mappWindowParent(windowID)
if mappWindowName(parentWin) = parentNameLookingFor then
set rightParent = TRUE
end if
return rightParent
end
mappGetWindowParent (
windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: integer window ID
Returns the windowID of the parent of the supplied window or 0
if it's a top-level window, or -1 if the supplied windowID can't
be found.
Example:
set parentID = mappGetWindowParent(28029632)
mappSetWindowParent (
windowIDNum, newParentWindowIDNum )
windowIDNum: integer window ID obtained from
another method
newParentWindowIDNum: integer window ID obtained from
another method
Returns: integer window ID or 0
Win32-only method. Assigns a new parent to a window. Returns
the windowID of the previous parent of the supplied window if
successful or 0 if not successful.
You can use this with some applications to make the target
window appear within the confines of the newly-assigned parent
window, and make it behave as if it is part of the new parent app
when windows are redrawn or when the new parent is sent to back or
moved to front. For instance specifying the Director stage for an
application's main window's parent may make the application appear
as though it is integrated within Director. This does not work
with all apps and so requires testing. It may produce strange
behavior, depending on how the app is coded.
Example:
set result = mappSetWindowParent(233,466)
mappGetHighestWindowParent
( windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: integer window ID or -1
Returns the windowID of the parent window highest up in the
hierarchy for the supplied window or -1 if the supplied window ID
is invalid. This is useful for dialog widget windows or tool
palette widget windows when you want to find out what main
application window owns them. Simply getting the parent of such a
widget will only return the dialog or palette window they are a
part of.
Example:
-- Returns TRUE if window supplied is a descendent
-- of the window name supplied
--
-- EX: set inHierarchy = isDescendentOf(13577236,"Message")
--
on isDescendentOf windowID,parentNameLookingFor
set rightParent = FALSE
set topWin = mappGetHighestWindowParent(windowID)
if mappWindowName(topWin) = parentNameLookingFor then
set rightParent = TRUE
end if
return rightParent
end
mappWindowName( windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: string window name or "Error: invalid
windowID"
Returns the window name of the supplied windowID. Useful at
runtime for determining the windowID of a window you want to
target. Return value may contain encoding for special
characters.
Also useful as an alternative method for
communicating with another external application. The two
applications can communicate by changing the window name of a
window created and placed off screen by one of the applications.
You must be able to code the external app to use this approach. It
won't work with a commercial application.
This is by no means the most efficient way for two applications
to communicate with each other,but it's good for triggering events
or passing small amounts of data(such as filenames) between
applications. Also, unlike AppleEvents or Windows DDE messaging,
the same basic approach will work on both Mac and Windows.
MasterApp wasn't developed for this purpose, but some enterprising
MasterApp customers have used this technique with success.
Example:
-- Reads the name of a window and interprets it
-- as data from other application
--
-- EX: readMessage(33432)
--
on readMessage windowID
set newData = value(mappWindowName(windowID))
case newData of
1:set msg = "External processing starting ..."
2:set msg = "External processing finished"
3:set msg = "Error in processing"
otherwise
set msg = ""
end case
put msg into field "Status"
end
mappGetWindowName (
windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: string window name or "" if window ID is
invalid
Returns the window name of the supplied windowID. Synonym for
mappWindowName.
Example:
set nam = mappGetWindowName(8899)
mappSetWindowName ( windowIDNum,
newNameString )
windowIDNum: integer window ID obtained from
another method
newNameString: string containing new name for window
Returns: integer status, 0 if successful, nonzero if an
error occurs
Sets the specified window's name. This may have side effects if
the app does not expect the window's name to change. Returns 0 if
successful, or nonzero if an error occurs (typically, a bad
windowID supplied).
You can set up a type of inter-app
communication using this method.
Example:
-- Changes the window name of a window at intervals
-- to create a blinking message, then returns the
-- name to the original
--
-- EX: warningMsg(8899,"-Danger!-",5,30)
--
-- Will blink the title Danger 5 times at 30 tick intervals
--
on warningMsg windowID, msgText, times, interval
set savedName = mappGetWindowName(windowID)
repeat with x = 1 to times
mappSetWindowName ( windowID, msgText )
mappFeedGenericTimeslice()
set waitUntil = the timer + interval
repeat while the timer < waitUntil
nothing
end repeat
mappSetWindowName ( windowID, "" )
mappFeedGenericTimeslice()
set waitUntil = the timer + interval
repeat while the timer < waitUntil
nothing
end repeat
end repeat
mappSetWindowName ( windowID, savedName )
mappFeedGenericTimeslice()
end
mappWindowHasChildren (
windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: integer TRUE(1) or FALSE(0)
Returns TRUE if the window has child windows, false if not or
if the supplied windowID is invalid. Useful for sifting through
the hierarchy of one parent window to see if any of the
descendants match a particular criteria.
Example:
-- Returns a list of grandchild windows of given window
--
-- EX: set gList = grandKids(87888)
--
on grandKids windowID
set winList = []
set topList = mappGetChildWindowIDs(windowID)
set num = the number of words of topList
repeat with x = 1 to num
set oneWin = value(word x of topList)
if mappWindowHasChildren(oneWin) then
set sublist = mappGetChildWindowIDs(oneWin)
set subtot = the number of words of subList
repeat with y = 1 to subtot
set grandWin = value(word y of subList)
if not getOne(winList,grandWin) then
append winList,grandWin
end if
end repeat
end if
end repeat
return winList
end
mappWindowType ( windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: string window type or "" if supplied window ID
is invalid
Returns the type of window. On the Mac, this is always an
integer, but this method returns a string containing the integer,
for compatibility with the Win version where windowTypes can be
strings.
Example:
set winType = mappWindowType(324)
mappGetWindowType (
windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: string window type or "" if supplied window ID
is invalid
Synonym for mappWindowType, for compatibility with earlier
releases.
Example:
-- Cycle through task's windows looking for
-- window of particular type
--
-- EX: set winID = findTaskWinOfType(43,"Main")
--
on findTaskWinOfType taskID,typeString
set foundWin = 0
set winList = mappGetTaskWindowIDs(taskID)
set num = the number of words of winList
repeat with x = 1 to num
set id = value(word x of winList)
if mappGetWindowType ( id) = typeString then
set foundWin = id
exit repeat
end if
end repeat
return foundWin
end
mappWindowIsVisible (
windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: integer TRUE(1) or FALSE(0)
Returns TRUE if the window is displayed (but possibly
obscured), or FALSE if it's hidden or the windowID was invalid
Example:
if mappWindowIsVisible(windowID) then
set windowCount = windowCount + 1
end if
mappFindWindow ( windowName,
windowType )
windowName: string specifying window name to look
for or 0
windowType: string specifying window type to look for or 0
Returns: integer window ID or string beginning with
"Error:"
32-bit Window only method. Get a windowID for the first parent
window matching the windowName and windowType. For windowName,
supply a string to check a windowName, or 0 for all windowNames.
For windowType, supply a string to check a windowType, or 0 for
all windowTypes. Returns a string for an error, or an integer with
the first found windowID. Example: see if Windows Paint accessory
is running with syntax like this: set alreadyRunning =
integerP(mappFindWindow(0,"MSPaintApp"))
You can use this method on Windows to solve the problem of an
overeager user whose feverish double-clicking at startup causes
more than one copy of the projector to launch. Have the projector
check for a window type of "ASIMainWndClass" for Director 6.* and
earlier projectors or "ImlWinCls" (third letter is a lower-case L)
for D7, and quit if a copy is already running.
Examples:
on startMovie
-- Quit if another D7 projector is running
if the platform = "Windows,32" then
if not stringP(mappFindWindow(0,"ImlWinCls")) then
quit
end if
end if
end
-- Substitute code for the Mac
--
-- Returns windowID of top level window for
-- task that corresponds to name. Does not
-- expect window name to contain a comma.
--
-- EX: set winID = findWindowNamed("MainApp",54)
--
on findWindowNamed theName,taskID
set winID = 0
set winList = mappGetTaskWindowList(taskID)
set ln = the number of lines of winList
set savDelim = the itemDelimiter
set the itemDelimiter = ","
repeat with x = 1 to ln
set oneWin = line x of winList
if item 1 of oneWin = theName then
set winID = value(item 2 of oneWin)
exit repeat
end if
end repeat
set the itemDelimiter = savDelim
return winID
end
mappGetActiveWindow ()
Returns: integer window ID
Returns windowID of the frontmost window (0 if no windows are
visible or active). Note: this only applies to windows owned by
the Director/Authorware task. Usually returns the same window as
mappDirectorStageWindow in
projectors, but could also return authoring-time windows, MIAWs,
or Xtra- or XObject-owned windows.
Example:
set winID = mappGetActiveWindow()
if mappWindowType(winID) = "Tool" then
mappCloseWindow(winID)
end if
mappSetActiveWindow (
windowIDNum)
windowIDNum: integer window ID of top level parent
window obtained from another method
Returns: integer window ID of previously active window
or 0 if unsuccessful
Sets a window owned by Director/Authorware authoring or the
Director/Authorware standalone to be the frontmost, active window
(making it visible, if it's hidden). Use mappWindowToFront
with other applications.
Director normally expects to activate its own windows, and its
notion of which window is active or frontmost may become confused
when using this command. If so, then sending fake mouse clicks to
activate the window may avoid this. This method will automatically
bring the Director task to the front, if it's not already. Use
this method with caution, as it can take over mouse and keyboard
input.
Example:
mappSetActiveWindow(3233)
mappGetForegroundWindow (
)
Returns: integer window ID
Win32-only method. Returns the windowID that the user is
currently working with. Can be easier to use than
mappGetParentWindowList() or mappGetParentWindowIDs(), since it
doesn't return floating Windows Explorer task bar windowID's,
etc.
Example:
set winID = mappGetForegroundWindow ( )
if mappGetWindowName(winID) <> "Main" then
mappWindowToBack(winID)
end if
mappSetForegroundWindow (
windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: integer 1 if successful, 0 if not
Win32-only method. Changes front to back draw order and gives
the window's task higher priority for processor time slices.
Similar to mappWindowToFront, but
more immediate.
Example:
-- Cycle through task's windows looking for
-- particular window name and make it
-- foreground window
--
-- EX: set winID = makeForeground(43,"Main")
--
on makeForeground taskID,windowName
set foundWin = 0
set winList = mappGetTaskWindowIDs(taskID)
set num = the number of words of winList
repeat with x = 1 to num
set id = value(word x of winList)
if mappGetWindowName ( id) = windowName then
set foundWin = id
mappSetForegroundWindow (foundWin)
exit repeat
end if
end repeat
return foundWin
end
mappGetKeyboardInputWindow
( )
Returns: integer window ID
On Windows, this is a distinct system call. On the Mac, there
is no such call,so this method is just a synonym for mappGetActiveWindow
on the Mac.
Example:
set winID = mappGetKeyboardInputWindow ( )
mappSetKeyboardInputWindow
( windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: integer window ID of window previously
receiving keyboard input or 0 if not successful
Sets the windowID to receive keyboard events. Supply 0 if you
want keyboard input to be ignored. On Windows, this is a distinct
system call, with no Mac equivalent; therefore, on the Mac, this
method is just a synonym for mappSetActiveWindow.
Example:
mappSetKeyboardInputWindow (34343)
mappCaptureMouseInput (
windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: integer window ID of window previously
receiving mouse input or 0 if not successful
Directs mouse input to the specified Director/Authorware
authoring or Director/Authorware projector window. For use only
with the host app's windows. The supplied windowID must already be
frontmost. This allows a window to react to mouse movement outside
its rectangle. This doesn't prevent other windows from being
activated by mouse clicks.
On Windows, this is a distinct system call. On the Mac, there
is no such call, so this method is just a synonym for mappSetActiveWindow
on the Mac.
Example:
mappCaptureMouseInput (3434)
mappReleaseMouseInput ( )
Returns: no return value
Reverses effect of mappCaptureMouseInput.
Frees mouse input to be received normally. No return value. On the
Mac, this method does nothing, because there's no Mac equivalent
for this Windows system call.
Example:
mappReleaseMouseInput ( )
mappGetParentWindowTopChild
( windowIDNum)
windowIDNum: integer window ID obtained from
another method or 0 to get the top window on the entire screen
Returns: integer window ID or 0 if unsuccessful or there
is no top child
Returns the topmost child window of the supplied parent
windowID. May return a 'floating palette' window, such as
Director's 'Control Panel' window. Supply 0 if you want the top
window on the screen. This can tell you if the Windows taskbar is
showing, if the windowType of the returned top window is
'Shell_TrayWnd'.
Windows window architecture differs from Mac. On Windows, each
app has a parent window which may contain other windows (entirely
within the parent). On the Mac, parent windows may appear anywhere
on the desktop, and the only "child" windows they can have are
controls such as a scrollbar or an edit field. On the Mac,
therefore, this method simply returns the first control owned by a
window or 0 if there are no controls.
Example:
set topWin = mappGetParentWindowTopChild(0)
if mappGetWindowType(topWin) = "Shell_TrayWnd" then
-- taskbar is showing
end if
mappGetDesktopWindow ()
Returns: integer window ID
Gets a windowID for the desktop, the screen 'parent' of every
parent window on Windows. Returns the windowID of the Mac desktop
itself (which may include multiple screens). If you are trying to
get the desktop dimensions, Director's own "the desktopRectList"
is a better option.
Example:
set desktop = mappGetDesktopWindow ()
mappGetWindowOutsideRect (
windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: string containing 4 coordinates of specified
window or string beginning with "Error:"
Returns a window's dimensions, relative to the main screen,
including any title bar area and window border as a four-word
string of integers in the order: left, top,right, bottom. Some
apps (Director itself included), that expect to maintain child
window dimensions privately, may return values that are offset
from true screen coordinates; testing is required for each app
with which you use this method.
Example:
-- Returns list containing horizontal and vertical
-- dimensions of a window
--
-- EX: put windimensions(202256)
-- [404, 377]
--
on winDimensions windowID
set h = 0
set v = 0
set theRect = mappGetWindowOutsideRect(windowID)
if offset("Error:",theRect) = 0 then
set h = value(word 3 of theRect) - value(word 1 of theRect)
set v = value(word 4 of theRect) - value(word 2 of theRect)
end if
return list(h,v)
end
mappGetWindowInsideRect (
windowIDNum)
windowIDNum: integer window ID obtained from
another method
Returns: string containing 4 coordinates of specified
window's content area or string beginning with "Error:"
Returns the dimensions of a window's content area as a
four-word string of integers in the order: left, top,right,
bottom. Does not include title bar or window border. Some apps
(Director itself included), that expect to maintain child window
dimensions privately, may return values that are offset from true
screen coordinates; testing is required for each app with which
you use this method.
Example:
set contentArea = mappGetWindowInsideRect(23232)
mappSetWindowOutsideRect (
windowIDNum, leftNum, topNum, rightNum, bottomNum )
windowIDNum: integer window ID obtained from
another method
leftNum: integer value for left window coordinate
topNum: integer value for top window coordinate
rightNum: integer value for right window coordinate
bottomNum: integer value for bottom window coordinate
Returns: 0 if successful, 1 if supplied dimensions are
invalid, 2 if supplied window ID is not valid
Sets outside window rectangle dimension and window position.
You can move or resize a window based on the dimensions you
provide. This method behaves differently on Mac and Windows. On
Windows, if you change the window size, the entire window and its
controls are redrawn to the new size. On the Mac, scroll bars and
other window content may not adjust to the new window size and
become unusable. Therefore, on the Mac, it's best to change only
the position of the window while maintaining its size. For better
window sizing results on the Mac simulate a user resize with
mappFakeMouseDrag.
Example:
-- Moves window above menu bar
--
-- EX: off screen(37273)
--
on offScreen windowID
set theRect = mappGetWindowOutsideRect(windowID)
if offset("Error:",theRect) = 0 then
set leftNum = value(word 1 of theRect)
set topNum = value(word 2 of theRect)
set rightNum = value(word 3 of theRect)
set bottomNum = value(word 4 of theRect)
set winHeight = bottomNum - topNum
set offSet = bottomNum + winHeight + 10
mappSetWindowOutsideRect(windowID,leftNum,topNum - offSet,rightNum,bottomNum - offSet)
end if
end
mappSetWindowRect ( windowIDNum,
leftNum, topNum, rightNum, bottomNum )
windowIDNum: integer window ID obtained from
another method
leftNum: integer value for left window coordinate
topNum: integer value for top window coordinate
rightNum: integer value for right window coordinate
bottomNum: integer value for bottom window coordinate
Returns: 0 if successful, 1 if supplied dimensions are
invalid, 2 if supplied window ID is not valid
Synonym for mappSetWindowOutsideRect,
for compatibility with earlier versions.
Example:
mappSetWindowRect ( 23445, 10, 10, 310, 210 )
mappCloseWindow ( windowIDNum )
windowIDNum: integer window ID obtained from
another method
Returns: integer status,. On Mac, 0 if successful, 1 if
supplied window ID is invalid, 2 if the window has no close box so
cannot be closed. On Win, -1 if supplied window ID is invalid, -2
if window hasn't quit yet.
Simulates a mouse press on a window's close box. Normal
behavior for Windows applications is to quit when the main window
is closed, so this is the best way to quit a Windows app. Closing
a window does not normally quit a Mac application. Use mappRudeQuitTask
to quit a Mac app.
Only windows that are frontmost and whose tasks are frontmost
can be closed on the Mac. Therefore, this method makes a window
frontmost if it's not already, and then closes it immediately. It
is up to you to move the window's task to the front with mappTaskToFront
before trying to close the window. The example handler
demonstrates how to do this for the Mac. Although the code will
work on Win as well, having to move the task to the front is a Mac
requirement.
On the Mac, this method does not work if the window does not
have a close box. Also, a window may not have a close box until
it's frontmost. Not all apps really close the window when the
close box is pressed. For instance Director authoring just hides a
window when the close box is pressed. In the cases where
mappCloseWindow does not work, you may need to send a fake menu
command to close the window, or send a fake mouse press to some
interface gadget within the window area itself, or use mappHideWindow
instead.
On the Mac, the default value MasterApp
uses for the center of the close box is 8 pixels from the top of
the window title bar, and 14 pixels from the left (pre System 8)
or 8 pixels from the left (System 8 and later). You can change
these values with the mappSetCloseBoxOffset
method. This method is useful when you need to use mappCloseWindow
on non-Roman systems or with extensions like 'Aaron' or the System
8 Appearance Manager that alter the look of window title bars. Use
mappFindWindowPart to get
information about the location of the current close box.
mappFindWindowPart only returns information about Director's own
windows, but since the close and zoom boxes in title bars of all
windows are in the same place, information you derive from a
Director window applies to any window of the same type. You may
have to create a Movie In A Window and position it off screen in
order to get a window with a close box, since the stage won't have
a close box.
On the Mac, a floating palette window may have a different
window bar appearance from, for instance, a standard document
window, and therefore different close and zoom box locations. You
would need to adjust the close box offset accordingly to close
such a window.
After issuing a closeWindow you want to give other applications
as well as Director itself an opportunity to redraw the areas that
may have been under the window that closed. Do this with
mappFeedGenericTimeslice for other apps. Lingo's "set the stage
color to the stage color" will redraw the Director stage.
Example:
-- Moves the task to front and feeds timeslices
-- to insure a successful closeWindow on Mac
--
-- EX: macCloseWindow(23445,43)
--
on macCloseWindow windowID,taskID
set waitLimit = 2 * 60
if not(windowID > 0) or not(taskID > 0) then
exit
else
mappTaskToFront(taskID)
repeat while not (integer(word 1 of mappGetTaskOrder()) = taskID)
mappFeedTimeslice(taskID)
end repeat
mappCloseWindow(windowID)
set stopWaiting = the ticks + waitLimit
repeat while the ticks < stopWaiting and mappWindowExists(windowID)
mappFeedTimeslice(taskID)
end repeat
end if
end
mappSetCloseBoxOffset (
horOffsetNum, verOffsetNum )
horOffsetNum: integer number of pixels center of
window's close box left edge is from left of window
verOffsetNum: integer number of pixels center of window's
close box top edge is from top of window
Returns: no return
Mac-only method. Allows you to change the default
assumption about the location of a window's close box. Affects
mappCloseWindow.
Example:
mappSetCloseBoxOffset ( 20, 20 )
mappFindWindowPart ( xLocNum,
yLocNum )
xLocNum: integer horizontal coordinate
yLocNum: integer vertical coordinate
Returns: integer code for window part or negative number
for error.
|
Code
|
Window Part
|
|
0
|
outside any of Director/Authorware's windows
|
|
1
|
in menu bar
|
|
2
|
in desk accessory window that's been launched in
Director/Authorware's memory partition
|
|
3
|
window content area (except any size boxes)
|
|
4
|
title bar
|
|
5
|
size box (active windows only)
|
|
6
|
close box
|
|
7
|
zoom box (standard state)
|
|
8
|
zoom box (user's state)
|
|
11
|
windowshade box
|
Mac-only method. Allows you to find what part of a window
belonging to Director/Authorware authoring or to a
Director/Authorware projector is under the specified coordinate.
Only applies to the Director/Authorware task's own windows but
information about the menu bar, title bar, close, size and zoom
boxes applies to all windows of the same type, since those
elements are the same for all application windows. Dimensions are
relative to the top left of the screen with the Finder menu bar.
The window must be visible, otherwise the return is always 0.
Gadgets 7 and 8, zoom box standard state and zoom box user's
state both occupy the same position on the menu bar right now,
although they could become two separate gadgets in different
locations in some future version of the Mac OS. The current state
of the window determines which gadget occupies the spot. For
instance if the user has resized the window, the standard state
gadget (7) will be in that position to allow the user to restore
the window to standard state. Otherwise the user state button will
be in that position to allow the user to resize the window. You
can tell from the window part returned, what the current state of
the window is and therefore what will happen next if the user or
MasterApp clicks the zoom box. But this will only work for
Director's own windows.
Example:
-- Find resize box of a Director window
-- Returns list containing hor and ver
-- coordinate to send start of mousedrag to
--
-- EX: put findResizeBox(12592448)
-- [1042, 683]
--
on findResizeBox windowID
set coords = [0,0]
set theRect = mappGetWindowOutsideRect(windowID)
if offset("Error:",theRect) = 0 then
set rightNum = value(word 3 of theRect)
set bottomNum = value(word 4 of theRect)
repeat with x = 1 to 50
repeat with y = 1 to 20
set h = rightNum - x
set v = bottomNum - y
if mappFindWindowPart(h,v) = 5 then
set coords = [h,v]
exit repeat
end if
end repeat
if coords <> [0,0] then
exit repeat
end if
end repeat
end if
return coords
end
mappWindowExists ( windowIDNum
)
windowIDNum: integer window ID obtained from
another method
Returns: integer TRUE(1) or FALSE (0)
Returns TRUE if the window still exists, FALSE if not.
Example:
set exists = mappWindowExists(57438)
mappWindowToFront
( windowIDNum )
windowIDNum: integer window ID obtained from
another method
Returns: windowID of window previously in front or 0 if
unsuccessful
Brings a window to the front. If the window's application is
not already in front, it will be made frontmost. Use this method
before directing simulated user input to a window.
Example:
on sendChar windowID,charToType
mappWindowToFront(windowID)
mappFakeCharacter(windowID,charToType)
end
mappWindowToBack ( windowIDNum
)
windowIDNum: integer window ID obtained from
another method
Returns: integer status code 0 if successful, -1 if
another error occurred
Sends a window to the back.
On the Mac, this only affects the drawing order of windows
within each application's window list. You can not move
applications to the back this way. Use mappWindowToFront
on the window you want frontmost instead.
Example:
mappWindowToBack(45333)
mappHideWindow ( windowIDNum )
windowIDNum: integer window ID obtained from
another method
Returns: integer status code 0 if successful, -1 if an
error occurred
Hides a visible window and makes its application frontmost if
it's not already. An app might not realize its window is hidden.
For instance, the Director authoring windows may need to be
selected twice in the menus to reappear.
Example:
-- Toggle window visibility on and off
--
-- EX: toggleVis(78737)
--
on toggleVis windowID
set vis = mappWindowIsVisible(windowID)
if vis = TRUE then
mappHideWindow(windowID)
else
mappShowWindow(windowID)
end if
end
mappShowWindow ( windowIDNum )
windowIDNum: integer window ID obtained from
another method
Returns: integer status code 0 if successful, -1 if an
error occurred
Shows a hidden window (and makes its application frontmost if
it's not already). To subsequently interact with the window, use
mappSetActiveWindow or
mappWindowToFront right after
this method.
Example:
mappShowWindow(windowID)
mappMinimizeWindow ( windowIDNum
)
windowIDNum: integer window ID obtained from
another method
Returns: integer status code 0 if successful, 1 if an
error occurred
On Windows, reduces the window to an icon on the Windows
toolbar if that window is capable of minimizing. Some document
sub-windows may minimize to a floating or tiled window bar
instead. Use mappWindowToFront on
both platforms before this method.
On Mac, since there is no "minimize", it is equivalent to the
user clicking the window's zoom box. This method, on Mac, will
only return the window to normal state if the window is currently
in a zoomed state.
Since MasterApp actually sends a click
to the zoom box on the Mac, this method will fail if the zoom box
is not in the default system position on the window. That can
happen if the user has customized window appearance for the system
or if a particular application offers a "classic appearance"
preference that makes its windows assume their own custom
appearance rather than the general system look. You can override
the default location of the standard state zoom gadget in the
window title bar with mappSetStandardZoomOffset.
Example:
-- Moves window to front and "clicks"
-- window's zoom box
--
-- EX: minimizeWin(78333)
--
on minimizeWin windowID
mappWindowToFront(windowID)
mappFeedGenericTimeSlice
mappMinimizeWindow(windowID)
mappFeedGenericTimeSlice
end
mappRestoreWindow ( windowIDNum
)
windowIDNum: integer window ID obtained from
another method
Returns: integer status code 0 if successful, -1 if an
error occurred
On Windows, restores a window to normal state after it has been
minimized. On the Mac, this method is a synonym for mappMaximizeWindow
which simulates a click on the zoom box.
Example:
mappRestoreWindow(34522)
mappMaximizeWindow ( windowIDNum
)
windowIDNum: integer window ID obtained from
another method
Returns: integer status code 0 if successful, 1 if an
error occurred
On Windows, expands a window to its maximum size, which usually
means full screen size for an application's main window. A
document window will usually expand to fill the application main
window area. Use mappWindowToFront
on both platforms before this method.
On Mac, since there is no "minimize", it is equivalent to the
user clicking the window's zoom box. This method, on Mac, will
only zoom the window if the window is currently not in a zoomed
state. If the window is currently zoomed, it will return to normal
state when this method is used.
Since MasterApp actually sends a click to the zoom box on the
Mac, this method will fail if the zoom box is not in the default
system position on the window.
Example:
mappMaximizeWindow(34522)
mappSetUserZoomOffset (
horPixelNum, verPixelNum )
horPixelNum: integer number of pixels center of
window's zoom box is from right of window
verPixelNum: integer number of pixels center of window's zoom
box is from top of window
Returns: no return
There is no use for this method currently, because the user
zoom box and the standard zoom box refer to the same gadget in the
window title bar. In a future Mac system they may become separate
gadgets, necessitating the use of both methods. However, whenever
you set mappSetStandardZoomOffset
you should also use this method to set the user zoom to the same
value since currently one physical gadget on the window performs
both functions.
Example:
mappSetUserZoomOffset(20,15)
mappSetStandardZoomOffset (
horPixelNum, verPixelNum )
horPixelNum: integer number of pixels center of
window's zoom box is from right of window
verPixelNum: integer number of pixels center of window's zoom
box is from top of window
Returns: no return
Allows you to override the MasterApp default assumption that
the center of the standard zoom gadget is located 8 pixels down
from the top of the window title bar and either 14 pixels in from
the right of the window (pre System 8) or 24 pixels in from the
right of the window (System 8 or above). This can be useful on
non-Roman system versions, or when third-party extensions like
'Aaron' or the Apple Appearance Control Panel change the layout of
the window title bars. Use mappFindWindowPart
to determine this information for Director's own windows on
non-Roman systems. Since the close and zoom boxes in title bars of
all windows of the same type are in the same place, information
you derive from a Director window applies to any window of the
same type.
Example:
-- Looks for the zoom box and resets zoom box click
-- target point. Only needed on non-US systems
-- or when layout of window has been
-- changed
--
-- EX: adjustZoomOffset(7838)
--
on adjustZoomOffset windowID
set hOff = 0
set vOff = 0
set found = FALSE
set sys = float(mappGetSystemVersion( ))
if sys < 8 then
set horOffset = 14
else
set horOffset = 24
end if
set theRect = mappGetWindowOutsideRect(windowID)
if offset("Error:",theRect) = 0 then
set rightNum = value(word 3 of theRect)
set topNum = value(word 2 of theRect)
set checkForZoomBox = mappFindWindowPart(rightNum - horOffset,topNum + 8)
if checkForZoomBox <> 8 and (checkForZoomBox <> 7)then
mappWindowToFront(windowID)
repeat with x = 1 to 50
repeat with y = 1 to 20
set h = rightNum - x
set v = topNum + y
set partUnderPoint = mappFindWindowPart(h,v)
if partUnderPoint = 8 or (partUnderPoint = 7) then
set found = TRUE
set hOff = x
set vOff = y
exit repeat
end if
end repeat
if found = TRUE then
exit repeat
end if
end repeat
end if
if found = TRUE then
mappSetStandardZoomOffset(hOff,vOff)
mappSetUserZoomOffset(hOff,vOff)
end if
end if
end
mappDirectorStageWindow
()
Returns: integer window ID
Director-only method. Returns the windowID of the Director or
projector stage. On the Mac,this is the same window as the one
returned by mappDirectorMainWindow.
This windowID can change if the monitor color depth or size is
changed on the fly.
Example:
set windowID = mappDirectorStageWindow()
mappHostAppMainWindow ()
Returns: integer window ID
Returns the main windowID for this Xtra's host application on
the PC. For Director this is the parent of the parent of the stage
window.
On the Mac this is a synonym for mappDirectorStageWindow
in Director or mappAuthorwarePresentationWindow
in Authorware.
Example:
set windowID = mappHostAppMainWindow()
mappDirectorMainWindow ()
Returns: integer window ID
Director-only method. Returns the main windowID of Director or
the projector. On the Mac, this is the same window as the stage
itself. Synonym for mappHostAppMainWindow.
Example:
set windowID = mappDirectorMainWindow()
mappAuthorwareMainWindow
()
Returns: integer window ID
Authorware-only method. Synonym for mappHostAppMainWindow.
Example:
windowID := mappAuthorwareMainWindow()
mappAuthorwarePresentationWindow
()
Returns: integer window ID
Authorware-only method.
Example:
windowID := mappAuthorwarePresentationWindow()
mappKeepOnTop ( windowIDNum )
windowIDNum: integer window ID obtained from
another method
Returns: "OK" or string beginning with "Error:"
Win32-only method. Window is displayed on top of all other
windows, even when other app's windows are activated. Useful for
making a Director projector behave like a floating tool
palette.
Example:
on startMovie
set windowID = mappDirectorMainWindow
mappKeepOnTop(windowIDNum)
end
mappDontKeepOnTop ( windowIDNum
)
windowIDNum: integer window ID obtained from
another method
Returns: "OK" or string beginning with "Error:"
Reverses effect of mappKeepOnTop.
Example:
mappDontKeepOnTop(3233)
MasterApp's Launch family of methods can either launch an
application with no initial document open, or launch an
application with the document specified in the
commandLineArgsString parameter. This allows you to open a
document with an application other than its creator, if the
application understands how to open the document type.
How the launch methods work
On both platforms MasterApp sends an open message to the system
with the path to the application in the appPathString argument. If
the second argument, commandLineArgString, contains a document
path, this is passed along to the system as well.
Because both paths are being interpreted by the system and not
Director itself, you must pass paths that the system understands.
Director's relative path symbols will not work because the system
does not know how to interpret them. Use mappLocateExecutable
to find the full path to an application. You can use Director's
"the moviePath" function to build the path to a document located
relative to your Director movie like so:
if the machineType = 256 then
set pathDelim = "\"
else
set pathDelim = ":"
end if
set docPath = the moviePath & "Docs" & pathDelim & "Mydoc.txt"
mappLaunch(appPath,docPath)
PC
The reason the second argument is called commandLineArgString
instead of simply docPath, is because the contents of the
parameter are appended as a command line argument to the
executable path with a space in between. The mappLaunch methods
are the equivalent of typing the executable path, followed by the
command line param into the Windows Run dialog box ( Start Menu
-> Run )
Some applications accept other command line parameters in
addition to or instead of a document path. Check the application's
documentation for a list of parameters. For instance, the
following causes Notepad to open and print a document:
Typed into Run Dialog:
C:\WINDOWS.95\NOTEPAD.EXE /P C:\TEMP\DOC.TXT
Issued from mappLaunch:
mappLaunch("C:\WINDOWS.95\NOTEPAD.EXE","/P C:\TEMP\DOC.TXT")
The following causes Acrobat to launch without a splash
screen:
C:\ACROBAT\ACRORD32.EXE /S
Issued from mappLaunch:
mappLaunch("C:\ACROBAT\ACRORD32.EXE","/S")
Current versions of both Internet Explorer and Netscape on the
PC running on a 32-bit operating system will accept a URL as the
command line argument. This enables you to launch a particular
browser and go directly to a URL like so:
mappLaunch("C:\Program Files\Netscape\Netscape.exe","http://www.updatestage.com/")
Use mappLocateExecutable
first to find the path to a particular browser from its executable
name. Director's own "goToNetPage" command can do something
similar to this, but it launches the user's default browser rather
than one you specify.
If you are launching a 16-bit application on 32-bit Win, use
mappGetShortFileName to
convert the file paths of both the application and the document to
8.3 DOS paths before passing them. If you are not sure if the
application you will be launching is 16-bit it is safest to
convert the file paths to short paths. 32-bit apps can handle
either short or long file paths.
Mac
On the Mac, there is no such thing as a command line argument.
You must pass either a full document path or "" for the
commandLineArgString parameter.
Troubleshooting failed launches
Use the value that the launch methods return to find out why a
launch did not happen. Your code must look for a string on the PC
(32-bit environment) which contains the Win32
API launch error number or a negative return on the Mac which
is a Mac system error. Be careful not to regard a negative return
value as an error on both platforms, since PC task ID's on Win95
and Win98 are negative.
The following are the most common reasons why applications fail
to launch:
- Either the document or the path name is invalid. If you are
building the paths with Lingo, try the launch method in Director's
message window with the absolute paths so you can verify that the
paths are valid. Do not pass paths containing Director's relative
path syntax.
- A filepath containing numToChar(0) will fail. This character
is rarely found in a valid file name but may appear in a hidden
system file name such as the hidden system desktop folder "Move
and rename"
- The application doesn't have enough memory to launch. This is
error -108 on the Mac.
- On Windows, you used MasterApp's rude quit method on a prior
open of the app. Don't use mappRudeQuit
on Win unless there is no other option. Use mappCloseWindow.
RudeQuit can leave files locked that the app was using and prevent
you from launching it again. Here's a typical launch error caused
by a prior rude quit:
------ Application Error --------
-- ACROBAT caused a not present --
-- fault in module WEBLNK16.API --
-- at 0002:BC1.
Windows launch error table
The following table lists the most common error numbers
returned inside a string starting with the word "Error", by
MasterApp Xtra on Windows by all of the launch methods in this
section and by mappOpenDocument
and mappPrintDocument. The error
numbers are standard Windows API system errors. This is by no
means the complete list. Download the freeware Windows API Error
Utility from the updateStage
downloads area to look up an error code not found on the list
below.
|
Most common Win32 system errors encountered on
launch
|
|
Error
|
Description
|
|
0
|
Out of memory or resources
|
|
2
|
File was not found
|
|
3
|
Path was not found
|
|
5
|
Access denied (Win95/98 only)
|
|
8
|
Out of memory (Win95/98 only)
|
|
11
|
Executable file was invalid. Either it was not a
Windows application or there was an error in the .EXE
image
|
|
26
|
Sharing error
|
|
27
|
Associations incomplete
|
|
28
|
DDE timeout
|
|
29
|
DDE fail
|
|
30
|
DDE busy
|
|
31
|
No association for the specified file type
|
|
32
|
DLL not found (Win95/98 only)
|
Mac system errors
On the Mac, MasterApp returns Mac system errors for problems,
like Director itself does. Here is a table with some of the more
common errors you may encounter. This is in NO way an exhaustive
list. Download a Mac system utility from the updateStage Xtras
downloads
area for a complete list.
|
Most common Mac system errors encountered on
launch
|
|
Error
|
Description
|
|
-35
|
No such volume, volume not found. Can happen
because:
- The file's type and creator code are missing or do
not match any application on any mounted volume.
- The desktop database for the volume needs
rebuilding.
- The original application associated with the
document has been deleted
- An older Mac system is running and the application
that handles the document is on a volume bigger than 2
gigabytes. This is a Mac OS issue.
|
|
-108
|
Not enough memory to launch application
|
|
-192
|
Damaged resource fork. Can happen if the document came
from a PC or was copied to a PC and copied back to the
Mac. Opening and saving the file in ResEdit on the Mac
may fix the problem.
|
mappLaunch ( appPathString,
commandLineArgsString )
appPathString: string containing full path to
executable
commandLineArgsString: string containing optional command
line arguments or ""
Returns: integer task ID on Win32 and Mac, instance ID
on Win 3.1 . If there is an error, returns a negative number that
is a Mac standard system error code on Mac or
string beginning with "Error: CreateProcess() failed, code " on
Win32 containing a Win system error
code.
Opens the application specified in appPathString. If
commandLineArgsString contains a document path, opens the document
with the application. If the application is already open, usually
that app will come to the front. An application must be programmed
to respond in this way, so it is possible to encounter an app that
does not automatically move to the front.
Example:
set err = mappLaunch("C:\WINDOWS.95\NOTEPAD.EXE","")
mappLaunchButDontActivate (
appPathString, commandLineArgsString )
appPathString: string containing full path to
executable
commandLineArgsString: string containing optional command
line arguments or ""
Returns: integer task ID on Win32 and Mac, instance ID
on Win 3.1 . If there is an error, returns a negative number that
is a Mac standard system error code on Mac or
string beginning with "Error: CreateProcess() failed, code " on
Win32 containing a Win system error
code.
Similar to mappLaunch, but usually won't switch an already
running application to the front, and won't launch new
applications in front. Whether or not the already-running app
switches to the front depends on how the app is programmed.
Some applications may not be able to launch but not activate.
Testing is required. Supplying a document may cause the app to
move itself to the front anyway.
Example:
set err = mappLaunchButDontActivate("Macintosh HD:Apps:Simple Text","")
mappLaunchHidden ( appPathString,
commandLineArgsString )
appPathString: string containing full path to
executable
commandLineArgsString: string containing optional command
line arguments or ""
Returns: integer task ID on Win32 and Mac, instance ID
on Win 3.1 . If there is an error, returns a negative number that
is a Mac standard system error code on Mac or
string beginning with "Error: CreateProcess() failed, code " on
Win32 containing a Win system error
code.
Launches an application but does not make it visible. Some
applications may not be able to launch hidden. Testing is
required.
Example:
set err = mappLaunchHidden("C:\PROGRAM FILES\ACRO\ACRORD32.EXE","D:\DOCS\MYDOC.PDF")
mappLaunchMinimized (
appPathString, commandLineArgsString )
appPathString: string containing full path to
executable
commandLineArgsString: string containing optional command
line arguments or ""
Returns: integer task ID on Win32 and Mac, instance ID
on Win 3.1 . If there is an error, returns a negative number that
is a Mac standard system error code on Mac or
string beginning with "Error: CreateProcess() failed, code " on
Win32 containing a Win system error
code.
On Windows, launches the app iconized in the Windows task bar,
if possible. There is no Mac equivalent so on the Mac this method
is a synonym for mappLaunchButDontActivate.
Some applications may not be able to launch minimized. Testing
is required.
Example:
set err = mappLaunchMinimized("D:\PROGRAM\BROWSER.EXE","")
mappLaunchMaximized (
appPathString, commandLineArgsString )
appPathString: string containing full path to
executable
commandLineArgsString: string containing optional command
line arguments or ""
Returns: integer task ID on Win32 and Mac, instance ID
on Win 3.1 . If there is an error, returns a negative number that
is a Mac standard system error code on Mac or
string beginning with "Error: CreateProcess() failed, code " on
Win32 containing a Win system error
code.
On Windows, launches the app with its main window maximized to
fill the screen. There is no Mac equivalent so on the Mac this
method is a synonym for mappLaunch.
Some applications may not be able to launch maximized. Testing
is required.
Example:
set err = mappLaunchMaximized("D:\PROGRAM\BROWSER.EXE","")
These methods provide path and
other information that can be used with the Launch group of
methods. Additionally mappOpenDocument
and mappPrintDocument
provide a more direct way to open and print documents.
How documents are linked to applications
The launch utility methods
mappLocateExecutable,
mappOpenDocument
and mappPrintDocument
rely on an association made by the system between a document and
its application. The same mechanism that makes an application
launch when you double-click it on the desktop, allows these
MasterApp methods to launch the right app. Mac and Windows systems
handle the association process differently. Understanding
how the two systems work will help you use the launch methods
successfully.
On Windows, a file's extension associates it with an
application. You can see the associations that are already set up
on the system by choosing View -> Options from any Windows
Explorer menu and clicking the File Types tab. Clicking the Edit
button with any file type selected will show the actions the
system can perform on a file of that type. The "open" action
should always be listed. Clicking again on the Edit button with
the "open" action highlighted will display the path to the
application that will launch if the document is
double-clicked.
The information displayed in View -> Options, is coming from
the Windows Registry. An application's installer makes new file
associations for its document types when it is installed. When you
edit the information in View -> Options you are actually making
changes to the registry. You can view the registry entries that
make file associations directly by using the system utility
REGEDIT.EXE and viewing the category HKEY_CLASSES_ROOT.
On the Mac, a file's creator code determines what application
will open when you double-click it. A doc opens with an
application that has the same creator code. You can view a Mac
file's creator code with Apple's ResEdit which is available off of
the updateStage download
area. However a file's creator code is not actually stored inside
the file itself. It is stored in the desktop database of the
volume where the file resides. The path to the associated
application is also stored in the desktop database.
Troubleshooting
If you have a problem launching an app by supplying a doc path
in the launch utility methods, the first thing to try is to
double-click it in Explorer or in the Mac Finder. If that doesn't
work either, it is a system problem.
In addition to the previous launch
troubleshooting suggestions, the most common problems in
launching an app with a document are:
- (Win) The registry entry for the document type is incorrect.
This can happen if the application has been removed manually by
the user, which leaves the registry entry pointing to an app path
that no longer exists. It can also happen if a subsequent
application's installer takes over that document type. For
instance, when you install Acrobat Exchange it registers itself to
handle PDF files that were previously handled by Acrobat
Reader.
- (Win) The application expects to be installed into a path with
no spaces and it hasn't been. Some applications, notably Acrobat
Reader, expect to be installed into the default path of
drive:\Acrobat\. If they are installed to a path with spaces in
it, the system will only return the path up to the space to
MasterApp's mappLocateExecutable method.
- (Mac) The desktop database has become corrupted and needs to
be rebuilt. There is a utility in the updateStage download
area that rebuilds the desktop.
- (Mac) The document file has been copied to the PC which does
not maintain creator code information, then back to the Mac. Or
the document file originated on the PC. Either way, such a file
copied to the Mac will not have the correct creator code. Use
ResEdit to assign the correct creator code to the file.
- (Mac) The document and/or application reside on a volume that
doesn't have a desktop database. This is true of CD's that are
mastered as ISO9660 rather than as hybrid or Mac file systems. In
this case, use mappLocateExecutable's alternate syntax to locate
the executable by name.
- (Win) Some older applications write their document
associations to WIN.INI in the section [Extensions]
instead of to the Windows Registry. The system will examine
WIN.INI at startup and make registry entries for the associations
it finds in WIN.INI, but you have to do a reboot after running
such an installer for the associations to make it in to the
registry. mappLocateExecutable,mappOpenDocument and
mappPrintDocument, which all rely on the registry, may not work
until a restart, with documents owned by such an application.
mappLocateExecutable (
filenameString )
filenameString: string containing either full path
to a document, or string containing just an executable name
Returns: string path to executable registered to handle
document or string path to folder containing executable if an
executable name is specified, or string beginning with "Error:"
followed by Win system error code on
Win or string description of the error on Mac. Return value may
contain encoding for special
characters.
This method can take two different kinds of arguments. If you
supply it with a document path, it returns the full path to the
application registered to handle the document. If you supply it
with just an executable name, it returns the full path to the
folder containing the application.
Finding the application registered to handle a document
When you supply a full document path MasterApp uses either the
Win system registry or the Mac's desktop database to locate the
associated application. This is the preferable usage of the two
because the lookup process does not take long.
On the Mac, MasterApp looks through the desktop database of all
mounted disks in this order: volume on which document is located,
all local volumes, all network volumes. As soon as some version of
an application to match the document is found on some disk, the
search is over.
Finding an application by name
On the Mac, you can supply the name of any file. It does not
have to be an executable, although searching for an executable is
far more useful. That means that the only way MasterApp has to
distinguish between the two different kinds of arguments is by
whether or not there are any path delimiters (:) in the string
passed. If a path delimiter is in the argument string, MasterApp
assumes the argument is the path to a document and tries to find
the app associated with it. If there is no path delimiter in the
argument string, MasterApp will return the path to the file
itself, not its associated app.
When you supply just an executable name on the Mac, MasterApp
searches though the volume catalog of all local volumes, then all
network drives, until it finds the application. This can take
quite awhile if the volumes are large.
On the PC, you have to supply the name of an executable for
this alternate usage. If you supply the name of a document
MasterApp will not find the path to the document - it will always
return the path to the associated app.
When you supply an executable name on Windows, MasterApp
searches for the application using any paths specified in the
current DOS path and any paths specified in the Location section
of WIN.INI. If the app is not found, the search ends there. On
Win, the search does not continue through all mounted volumes as
it does on Mac.
Many application installers create a registry entry that
includes the full path to the installed application. Another
alternative, if mappLocateExecutable fails, is to look up the
executable name at this path using mappGetWindowsRegistry:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\[program name]
where program name is the name of your EXE like so:
set path = mappGetWindowsRegistry("HKEY_LOCAL_MACHINE","SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\Winword.exe","")
Examples:
-- find the app associated with this doc
set appPath = mappLocateExecutable("C:\TEMP\BOOK.TXT")
-- find the path to this app
set appPath = mappLocateExecutable("NOTEPAD.EXE")
mappLocateAliases ( )
Returns: no return
Mac-only method. This method causes mappLocateExecutable
to regard aliases as valid files when searching for an executable
by supplied executable name. When mappLocateAliases is turned on,
mappLocateExecutable may return the path to an alias. The default
for mappLocateAliases is off. Use mappResolveAlias
to find the actual path pointed to by an alias.
Example:
mappLocateAliases()
mappDontLocateAliases ( )
Returns: no return
Mac-only method. This method causes mappLocateExecutable
to ignore aliases when searching for an executable by supplied
executable name. The default for mappLocateAliases is off so there
is no reason to use this method unless mappLocateAliases has
previously been turned on.
Example:
mappDontLocateAliases()
mappResolveAlias ( filePathString
)
filePathString: string containing full path to
alias file
Returns: string path to original file if the file is an
alias or string beginning with ":Error:"
Returns the file path of the real file that the supplied alias
points to. Returns ":Error" if the file is not an alias. Note the
initial colon, which distinguishes an error from a validly
resolved file or folder on a hard drive named 'Error' Return value
may contain encoding for special
characters.
Example:
set realFile = mappResolveAlias ("Macintosh HD:Folder:IamAnAlias")
mappGetMenuBarHeight ( )
Returns: integer height of menu bar in pixels
Mac-only method. Returns the current height of the menu bar.
Use this method to retrieve default state of menu bar before
hiding it by changing its height. You cannot assume that the
default normal height is 20 pixels. That is determined by the
system script.
If you are running in a projector that has not installed menus,
you should use Director's "installMenu" command to install a menu
temporarily before trying to read the menu bar height.
- Make a field cast member called say "fakemenu" with minimal
text to create a small menu:
menu: @
menu: File
Quit/Q( | nothing
- Use the following code to install the menu and set the
height:
installMenu "fakeMenu"
Example:
global saveMenuHeight
installMenu "fakeMenu"
set saveMenuHeight = mappGetMenuBarHeight()
installMenu 0 -- remove the menu
mappSetMenuBarHeight (
pixelNumber )
pixelNumber: integer height of menu bar in pixels
Returns: integer previous menu bar height in pixels
Mac-only method. You can use this method to hide the menu bar.
You may also have to use it to restore a
normal menu bar after launching some applications. To hide the
menu bar, set its height to 2 rather than 0. Setting it to 0 will
not always hide it but setting it to 2 will, because that makes it
too small to display.
Example:
on hideMenuBar
global saveMenuHeight
set saveMenuHeight = mappGetMenuBarHeight()
mappSetMenuBarHeight(2)
end
mappFixMenuBarOnLaunch
Returns: no return
Mac-only method. Turns on menu bar fixing for launched external
applications. When the previous XObject version of MasterApp was
used to launch another application from a Mac projector that did
not have a menu installed, some apps, such as Acrobat, would
display their menu bar obscured behind another blank menu bar or
would not display a menu bar at all. That's because the projector
had set the menu bar height to 0.
This property, which is MasterApp's default state, fixes the
problem automatically by setting the menu bar height to a default
of 20 (unless another value has been set by mappFixMenuBarHeight)
before launching the external application, then setting it back to
0 when the projector is the foreground app. This method is new to
the MasterApp Xtra and obviates the need for the previous
workaround, which was to install a menu via Lingo's "installMenu"
command and set the menu bar height to 20 before launching the
external application.
Since this is MasterApp's default behavior, there is no need to
use this method unless you have previously turned off menu bar
fixing with mappDontFixMenuBarOnLaunch
Example:
mappFixMenuBarOnLaunch()
mappDontFixMenuBarOnLaunch
Returns: no return
Mac-only method. Turns off the default menu
bar fix. Only necessary if you don't want the launched
application to display a menu.
Example:
mappDontFixMenuBarOnLaunch()
mappFixMenuBarHeight (
pixelNumber )
pixelNumber: integer height of menu bar in pixels
Returns: no return
Mac-only method. Sets the menu bar height in pixels used by the
menu bar fix. You may need
to adjust the menu bar height from its default of 20 pixels if you
are not running on a US system. Other systems may have different
menu bar heights to accommodate their default system font. You can
use mappGetSystemScript to
determine if you are running on a non-US system, then install a
temporary menu and use mappGetMenuBarHeight
to determine the correct menu bar height to use.
Example:
on checkForeign
-- If value not 0 (US System)
if mappGetSystemScript() <> 0 then
installMenu "fakeMenu"
set menuHeight = mappGetMenuBarHeight()
installMenu 0 -- remove the menu
mappFixMenuBarHeight(menuHeight)
end if
end
mappGetSystemScript ( )
Returns: integer representing current system
script
Mac-only method. The Mac system script is the current method
used to show words on the screen. It is a set of properties that
includes the current keyboard layout, the characters in the
character set, and the ordering and formatting of the text on
screen - for instance left to right or right to left. Because the
system script governs the size of the characters it affects the
height of the menu bar. The Roman system script (US systems and
most European countries use the Roman script) has a menu bar
height of 20.
System Script Values
--------------------
0 Roman
1 Japanese
2 Traditional Chinese
3 Korean
4 Arabic
5 Hebrew
6 Greek
7 Cyrillic
8 Right-to-left symbols
9 Devanagari
10 Gurmukhi
11 Gujarati
12 Oriya
13 Bengali
14 Tamil
15 Telugu
16 Kannada/Kanarese
17 Malayalam
18 Sinhalese
19 Burmese
20 Khmer
21 Thai
22 Laotian
23 Georgian
24 Armenian
25 Simplified Chinese
26 Tibetan
27 Mongolian
28 Geez/Ethiopic
29 Extended Roman for Slavic and Baltic languages
30 Extended Roman for Vietnamese
31 Extended Arabic for Sindhi
Example:
set currentScript = mappGetSystemScript()
mappGetSystemRegion ( )
Returns: integer representing current system
region
Mac-only method. A region code is a breakdown within a
system script that further
distinguishes how characters are represented on the screen.
Because the system script and region govern the size of the
characters, this system property affects the height of the menu
bar.
This method is most useful for situations where an application
name will vary depending on the language of the host system. For
instance, French and English versions of an application might be
named "Cats" in English and "Les Chats" in French. If you wanted
to find the application on the task list at runtime you could
first test the system region to find out what the system language
was, and then you would know which application name to look
for.
System Region Values
--------------------
0 United States
1 France
2 Great Britain
3 Germany
4 Italy
5 Netherlands
6 French for Belgium and Luxembourg
7 Sweden
9 Denmark
10 Portugal
11 French Canada
13 Israel
14 Japan
15 Australia
16 the Arabic world
17 Finland
18 French for Switzerland
19 German for Switzerland
20 Greece
21 Iceland
22 Malta
23 Cyprus
24 Turkey
25 Croatian system for Yugoslavia
33 Hindi system for India
34 Pakistan
41 Lithuania
42 Poland
43 Hungary
44 Estonia
45 Latvia
46 Lapland
47 Faeroe Islands
48 Iran
49 Russia
50 Ireland
51 Korea
52 People's Republic of China
53 Taiwan
54 Thailand
Example:
set currentRegion = mappGetSystemRegion()
mappGetShortFileName (
filepathString )
filepathString: string containing long file path
Returns: string short DOS-style file path on PC,
unmodified string on Mac
16-bit applications, even running under 32-bit Win systems,
usually require DOS-style file paths. Use this method for
converting long paths before passing them as arguments when
launching 16-bit applications with any of the launch methods.
Example:
put mappGetShortFileName( "C:\Program Files\Outlook Express\ _isetup.exe")
-- "C:\PROGRA`1\OUTLOO`1\_ISETUP.EXE"
mappGetLongFileName (
filepathString )
filepathString: string containing short DOS-style
file path
Returns: string containing long file path, unmodified
string on Mac
Converts between MS-DOS 8.3 compliant short file names and long
file names.
Example:
set longPath = mappGetLongFileName("C:\PROGRA`1\OUTLOO`1\_ISETUP.EXE")
mappOpenDocument ( docpathString
)
docpathString: string full path to document
Returns: integer task ID on Mac, "OK" on Win32 or
instance ID on Win 3.1 if successful. If there is an error,
returns -1 for "File not found" on Mac, otherwise Mac
standard system error codes on Mac or string beginning with
"Error: couldn't launch application, error code " on Win32
containing a Win system launch error
code.
On a 32-bit Win operating system, if you supply a URL in
docPathString, the default browser will launch and connect to the
URL if the user has set up the browser to auto-connect.
Example:
set err = mappOpenDocument("C:\TEMP\MANUAL.DOC")
mappPrintDocument ( docpathString
)
docpathString: string full path to document
Returns: integer task ID on Mac, "OK" on Win32 or
instance ID on Win 3.1 if successful. If there is an error,
returns -1 for "File not found" on Mac, otherwise Mac
standard system error codes on Mac or string beginning with
"Error: couldn't launch application, error code " on Win32
containing a Win system launch error
code.
Example:
set err = mappPrintDocument("D:\MAIN\HELP.TXT")
mappInstanceTask ( instanceIDNum
)
instanceIDNum: integer instance ID returned from a
previous call
Returns: integer task ID or 0 if unsuccessful
Useful only on 16-bit Windows platform where the launch methods
return an instance ID rather than a task ID.
Example:
set taskID = mappInstanceTask(73827)
mappInstanceIsRunning (
instanceIDNum )
instanceIDNum: integer instance ID returned from a
previous call
Returns: integer TRUE(1) or FALSE (0)
Returns TRUE if the app is still running. Useful only on 16-bit
Windows platform where the launch methods return an instance ID
rather than a task ID.
Example:
set stillRunning = mappInstanceIsRunning(38277)
mappUnloadInstance (
instanceIDNum, appOrDLL )
instanceIDNum: integer instance ID returned from a
previous call
appOrDLL: string "app" or "dll" indicating what type of app
the target instance is
Returns: 0 if the program's already quit, -4 if it's
still running, -2 if taskID is invalid. It's not unusual to see -4
as a result. On Win32, -4 is *always* the result.
Useful only on 16-bit Windows platform. Synonym for mappRudeQuitTask
on the Mac and 32-bit Win. On Mac, the appOrDLL param is
irrelevant but must still contain a string.
Example:
set err = mappUnloadInstance(-38928,"app")
The input simulation family of
methods enables you to send simulated user mouse clicks and drags,
key presses and menu choices to an application to control the
application from Director. On both Mac and Win systems, when a
user performs a mouse or keyboard action, the system adds the
action to the system event queue. The system event queue contains
mouse and keyboard actions in the order that they happened. An
application receives information about user actions by monitoring
the event queue for actions intended for the application. This is
called polling or processing the event queue.
What happens after an app retrieves an
event from the queue differs on Mac and Win. On Win the system
routes the event to the intended window. On Mac, the app decides
which window to send the event to, based on which app and window
are foremost at the time of the event.
MasterApp can use two approaches to
simulate user input. It can add simulated events to the event
queue on Mac and Win, or, on Win32 only, it can bypass the event
queue, send an event message straight to the target window's
procedure for handling that event, and wait for the window
procedure to respond that it is done handling the event message.
The input simulation methods that end in "wait" use the second
technique.
Generally commercial apps respond to
system messages in the same way, but not always. If the standard
simulated input method doesn't work on Win32 systems, the
corresponding "wait" method might work for these apps. Otherwise
there is nothing that can be done about this because it is
governed internally by the application's code.
The individual widgets such as buttons
and text fields are considered child "windows" of their parent
window. It may take some investigation to determine which window
you should be sending your input to at runtime.
Two things that are key (no pun intended)
to making simulated input work:
- The window receiving the input has to
be frontmost on Mac and it's a good idea to make it frontmost
on Win as well
- The application has to have some time
to process the event queue after you have sent the
event.
When a user is actually typing or mousing
in an application the target window is always foremost. That's how
the system expects things to work and that's what you generally
ought to do with simulated input as well.
Also, you have to give the application
some time to process the event queue after sending the input.
Remember that as long as Lingo is processing further Lingo
commands after you have sent the simulated input, the other
application is not getting time to process the event queue and
react to the input. You should use mappFeedGenericTimeslice
after sending any simulated input command to cede time to the
other process. You may have to adjust the amount of timeslice time
to feed the other process depending on the system and the kind and
frequency of the simulated input commands you are sending. The
following "timeslice feeder" is a good handler to use for
this:
on feedProcess waitTicks
-- Make Director give over the specified processing time to allow
-- other tasks to process
--
-- EX: feedProcess(30)
--
set waitOver = the ticks + waitTicks
repeat while the ticks < waitOver
mappFeedGenericTimeSlice()
end repeat
end
How to allow Director adequate
processing time
If you are working with Director's own application windows, for
instance if you are sending simulated input to type in a Director
dialog or moving say, Director's cast window, you have to use a
different strategy for giving "the application" (Director) time to
check the event queue and process the events. Feeding timeslices
is counterproductive here, because it feeds timeslices to
applications OTHER than Director.
Director checks system queues and other system polling in the
idle time between frames. No system polling happens while Director
is executing code inside a handler, so a long repeat loop or
sequence of Lingo commands will not work for manipulating
Director's own windows. You must exit the current handler to allow
idle time processing. The easiest way to do this is to put
MasterApp simulated input methods or window operations intended
for Director's own windows on separate frames. You can also create
an object that issues commands in sequence on successive
stepFrames, or use a timeoutscript.
mappFakeMouseClick ( windowIDNum ,
horPointNum, verPointNum )
windowIDNum: integer window ID obtained from
another method
horPointNum: integer horizonal point relative to top/left
corner of desktop
verPointNum: integer vertical point relative to top/left
corner of desktop
Returns: 0
Simulates a mouse click and release at
point(horPointNum,verPointNum) by putting the mouse click event
into the event queue. If the windowID is not the frontmost window,
this method makes it so before faking the mouse click on Mac. On
Windows, the window is not automatically made frontmost. Supply 0
as the windowID if you don't want the click sent to any specific
window. If you target a specific window, but the coordinates you
specify fall outside of the window's area the click could activate
other applications. This method cannot send clicks to menus,
unfortunately. Use mappFakeCharCode
to select menu items that have keyboard shortcuts.
Example:
on sendClick windowID,hor,ver
-- Send a fake mouse click to a window
-- If no horizontal and vertical coords are specified, send the
-- click to the center of the window
-- Coordinates are relative to desktop, not window
--
-- EX: sendClick(2302,30,40) -- to point(30,40) on windowID 2302
-- sendClick(2302) -- to window center
--
if the paramCount = 1 then
-- No coords passed in so calculate hor and ver for center
-- of window
set winRect = getWindowOutsideRect(windowID)
set left = value(word 1 of winRect)
set right = value(word 3 of winRect)
set hor = left + integer((right - left) / 2)
set top = value(word 2 of winRect)
set bot = value(word 4 of winRect)
set ver = top + integer((bot - top) / 2)
end if
if not (integerP(hor) and integerP(ver)) then exit
windowToFront(windowID)
fakeMouseClick(windowID,hor,ver)
mappFeedGenericTimeslice()
end
mappFakeMouseClickWait (
windowIDNum , horPointNum, verPointNum )
windowIDNum: integer window ID obtained from
another method
horPointNum: integer horizonal point relative to top/left
corner of desktop
verPointNum: integer vertical point relative to top/left
corner of desktop
Returns: 0
On Win32, generates the same event as mappFakeMouseClick
but sends it directly to the window rather than placing it in the
event queue, and waits for the window to report that the event has
been processed. On the Mac, a synonym for mappFakeMouseClick.
Example:
mappFakeMouseClickWait(4593,200,340)
mappFakeMouseDrag ( windowIDNum,
fromHorNum, fromVerNum, toHorNum, toVerNum )
windowIDNum: integer window ID obtained from
another method
fromHorNum: integer horizonal point relative to top/left
corner of desktop where drag should start
fromVerNum: integer vertical point relative to top/left
corner of desktop where drag should start
toHorNum: integer horizonal point relative to top/left
corner of desktop where drag should end
toVerNum: integer vertical point relative to top/left
corner of desktop where drag should end
Returns: 0
Mac-only method. Simulates dragging the mouse from the "from"
coordinate supplied to the "to" coordinate supplied in the
specified window. Makes the window frontmost, if it's not already
frontmost. Supply 0 as the windowID if you don't want the drag
sent to any specific window.
This method will not work to make menu selections. Use
mappFakeCharCode to select menu
items using keyboard shortcuts.
Example:
-- Simulates user drag to resize a window.
-- Safer on Mac than changing window rect using
-- mappSetWindowOutsideRect
--
-- EX: dragResizeWin(38383,50)
--
on dragResizeWin windowID,pixels
set theRect = mappGetWindowOutsideRect(windowID)
if offset("Error:",theRect) = 0 then
set pixels = pixels + 10
set startH = value(word 3 of theRect) - 10
set startV = value(word 4 of theRect) - 10
set endH = startH + pixels
set endV = startV + pixels
mappWindowToFront(windowID)
mappFakeMouseDrag(windowID,startH,startV,endH,endV)
mappFeedGenericTimeSlice()
end if
end
mappFakeCharacter ( windowIDNum ,
charString )
windowIDNum: integer window ID obtained from
another method
charString: one-character string containing a printable
(visible) character
Returns: 0
Sends a printable ASCII character in the range 1 to 127 by
putting the character event on the event queue. Assumes the use of
the standard US English keyboard layout. Use mappFakeCharCode
to work with other keyboard layouts or languages.
Only editable text windows such as document windows or fields
in dialogs will accept keyboard input. On the PC for most apps,
the window must be of window type "Edit" to accept the characters.
On the Mac, a document window will accept the characters. For a
dialog box you may have to do some experimenting to see which
"window" represents the field that will accept the characters.
Example:
on sendString windowID,theString
-- Sends a string of printable characters to the specified windowID
-- Brings the window to the front first
--
-- EX: sendString(2302,"hi there")
--
if windowID = 0 then exit
if not stringP(theString) then exit
set le = length(theString)
mappWindowToFront(windowID)
repeat with x = 1 to le
mappFakeCharacter(windowID,char x of theString)
mappFeedGenericTimeSlice()
end repeat
end
mappFakeCharacterWait (
windowIDNum , charString )
windowIDNum: integer window ID obtained from
another method
charString: one character string containing a printable
(visible) character
Returns: 0
On Win32, generates the same event as mappFakeCharacter
but sends it directly to the window rather than placing it in the
event queue, and waits for the window to report that the event has
been processed. On the Mac, a synonym for mappFakeCharacter.
Example:
mappFakeCharacterWait(1523,"b")
mappFakeCharCode ( windowIDNum,
charNum, codeNum )
windowIDNum: integer window ID obtained from
another method
charNum: integer virtual keycode value obtained from
formula
codeNum: integer modifier keycode value
Returns: 0
Sends a non-printable control code to the specified window,
such as Escape or Ctrl-C, by putting the event into the event
queue. Unlike fakeCharacter you do not have to send
mappFakeCharCode to a text editing window.
However, some windows will not accept fake keycodes for some
keys. For instance, it does not work to send a tab character to a
dialog box to tab between text boxes or between default button
choices, although tab does work in text editing windows to advance
a set number of spaces. That is because applications don't process
some control keys directly. They rely on the system to intercept
the keys and send them a higher-level event that tells them what
action to take. For instance, dialog boxes are expecting to get a
"jump to next item" event, which is generated by the system when
the user tabs, but isn't generated by the system when you put the
event in the event queue manually.
The two arguments charNum and codeNum specify together the
control code to send. The following table lists the codes for the
most popular control keys:
|
PC
|
Mac
|
|
Key
|
CharNum
|
CodeNum
|
Key
|
CharNum
|
CodeNum
|
|
Tab
|
9
|
15
|
Tab
|
12297
|
0
|
|
Return
|
13
|
28
|
Return
|
9229
|
0
|
|
Ctrl-C
|
3
|
46
|
Ctrl-C
|
2147
|
1
|
|
Ctrl-X
|
24
|
45
|
Ctrl-X
|
1912
|
1
|
|
Ctrl-V
|
22
|
47
|
Ctrl-V
|
2307
|
1
|
|
Esc
|
27
|
1
|
Ctrl-Q
|
3185
|
1
|
The process for obtaining the codes to use for other control
keys differs between the two platforms.
PC
Download the Microsoft utility Virtual Keyboard from the Xtras
download
area. Launch the utility and press the key combination you are
interested in. You will see many messages in the Virtual Keyboard
window because repeat messages are generated as long as you hold
down the keys. You are interested only in WM_CHAR messages which
appeared while all of the keys were held down. Use the value under
Char for the argument charNum. Use the value under Scan for the
argument codeNum.
The screen shot below shows the WM_CHAR message for Ctrl-V
highlighted. Assuming a window ID of 35, the arguments for sending
Ctrl-V (on a US keyboard) would be:
--mappFakeCharCodeWait(windowID, charNum, codeNum)
mappFakeCharCodeWait(35,22, 47)
Some rare key combinations do not generate unique WM_CHAR
messages - Shift-Space for instance. You will not be able to use
mappFakeCharCode or mappFakeCharCodeWait for those key
combinations.
.dmg/Serious Software/Masterapp demo/Doc/graphics/key.gif)
Mac
On the Mac, it's not quite so easy. Open up a copy of your
System file with ResEdit. Get ResEdit from the Apple link supplied
in the Xtras Download
area. Look for the KCHR resource. Double-click it and then
double-click on the language you are interested in. It will bring
up a virtual keyboard that looks like the following:
.dmg/Serious Software/Masterapp demo/Doc/graphics/mackey.gif)
Press the key combination you are interested in. The keys will
highlight on the picture of the keyboard and two values will
display for Char and Key to the right. Unfortunately they are Hex
values and you have to do some math to extract the decimal values
that MasterApp requires. Here are the formulas:
This example uses the values for Cmd-V, which is Char $76, Key
$09
CharNum:
1. Convert the Char hex value to decimal. For $76 that would be
7 * 16 + 6 or 118
2. Convert the Key hex value to decimal. For $09 that would be
9
3. Multiply the Key decimal value by 256. 9 * 256 is 2304
4. Add the final Key decimal value to the final Char decimal
value. That would be 2304 + 118 = 2422
CodeNum
Add the following values together for any modifier keys that
are held down. In this example only Ctrl is being held down, so
the value would be 1.
right control = 128
right option = 64
right shift = 32
left control = 16
left option = 8
caps lock = 4
left shift = 2
left command = 1
--mappFakeCharCodeWait(windowID, charNum, codeNum)
mappFakeCharCodeWait(35, 2422, 1)
The methods in MasterApp are very close to the actual system
API calls, which require the same values for the charNum and
codeNum arguments. The advantage of this is that there isn't too
much intervening code that could introduce error. That makes
MasterApp a stable product, but it requires Lingo programmers to
do some extra work. The mappFakeCharCode methods are slated to be
revamped to use Director keycode args in a future version.
Examples:
-- Send Ctrl-V on the PC
mappFakeCharCode(9988,22,47)
-- Send Ctrl-V on the Mac
mappFakeCharCode(9988,2307,1)
mappFakeCharCodeWait (
windowIDNum, charNum, codeNum )
windowIDNum: integer window ID obtained from
another method
charNum: integer virtual keycode value obtained from
formula
codeNum: integer modifier keycode value
Returns: 0
On Win32, generates the same event as mappFakeCharCode
but sends it directly to the window rather than placing it in the
event queue, and waits for the window to report that the event has
been processed. On the Mac, a synonym for mappFakeCharCode.
Examples:
-- Send Esc on the PC
mappFakeCharCodeWait(9988,27,1)
-- Send Ctrl-Q on the Mac
mappFakeCharCodeWait(9988,3185,1)
mappShowMenu ( windowIDNum )
windowIDNum: integer window ID obtained from
another method
PC-only method. Targets the menu to receive keyboard input,
which allows you to send keyboard shortcuts to choose menu items.
Does this by adding a showMenu event to the event queue. The
process is equivalent to the user pressing Alt and then a key to
invoke that menu command. You must send mappShowMenu to the app's
main window, after moving it to the front. Then use mappFakeCharacter
to choose a menu item by sending the key.
These methods are only necessary on the PC because on the Mac
you can target any window with a keyboard shortcut for a menu
command and it will execute. On the PC, you first have to invoke
the menu and target the application's main window.
Example:
on sendToMenu windowID,theString
-- PC only. Activate the application's menu and then send the letter representing
-- the menu command. For instance sending "FX" for the menu command on
-- the PC will choose "[F]ile -> E[x]it" and quit the target application.
-- You must send menu commands to the app's main window for them to work.
-- If the character displays a submenu, send a second character for the
-- submenu choice.
--
-- EX: sendToMenu(2302,"FX")
--
if windowID = 0 then exit
if not stringP(theString) then exit
mappWindowToFront(windowID)
mappShowMenu(windowID)
mappFeedGenericTimeslice()
set le = length(theString)
repeat with x = 1 to le
mappFakeCharacter(windowID,char x of theString)
mappFeedGenericTimeslice()
end repeat
end
mappShowMenuWait ( windowIDNum
)
windowIDNum: integer window ID obtained from
another method
PC-only method. On Win32, generates the same event as mappShowMenu
but sends it directly to the window rather than placing it in the
event queue, and waits for the window to report that the event has
been processed.
Example:
mappShowMenuWait(389277)
mappAnyWindowAtPoint (
horPointNum, verPointNum )
horPointNum: integer horizonal point relative to
top/left corner of desktop
verPointNum: integer vertical point relative to top/left
corner of desktop
Returns: integer window ID or -1 if an error
occurred
Returns the parent window under point(horPointNum,verPointNum).
Useful when researching where to send fake mouse clicks, as a
diagnostic tool. The coordinates are relative to the top/left of
the desktop. On a Mac with multiple monitors the coordinates are
relative to the top/left of the screen with the menu bar.
Example:
set dialog = mappAnyWindowAtPoint(320,140)
mappChildWindowAtPoint (
windowIDNum , horPointNum, verPointNum )
windowIDNum: integer window ID obtained from
another method
horPointNum: integer horizonal point relative to top/left
corner of desktop
verPointNum: integer vertical point relative to top/left
corner of desktop
Returns: integer window ID or -1 if an error
occurred
Returns the child window - usually a widget like a button or
field, that is under point(horPointNum,verPointNum) in the parent
window supplied. Useful when researching where to send fake mouse
clicks, as a diagnostic tool. The coordinates are relative to the
top/left of the desktop. On a Mac with multiple monitors the
coordinates are relative to the top/left of the screen with the
menu bar.
Example:
set dialogWin = mappAnyWindowAtPoint(320,140)
set widget = mappChildWindowAtPoint(dialogWin,320,140)
The Windows registry contains
configuration information for the system and for individual
applications. You can use the registry to find out information
about a particular application, such as its install directory. You
can also use it to find out configuration information like whether
or not a screen saver is active. The Mac does not have a
comparable system registry so this method family is
Win32-only.
In early versions of Windows, all
customization information was stored in plain text .INI files.
Anybody could edit the files with a text editor, leaving open the
possibility of doing serious damage by writing the wrong
information in the wrong format. On 32-bit Windows systems
registry information is stored in a series of binary files that
can only be written to or read from, by using API calls. This
setup makes it more difficult for a user to incorrectly edit the
registry and possibly corrupt it. MasterApp gives you access to
these API calls in its Windows Registry family of
methods.
In order to use the registry methods you
have to know something about the way the registry is set up and
about where the registry stores the information you are interested
in. You can examine the registry on a Win machine by running
REGEDIT.EXE ( Start -> Run -> REGEDIT )
[While the average user would
probably not be able to completely corrupt the registry using
registry editing tools, it is quite possible to use MasterApp's
registry methods to wipe out registry entries or to write bad data
to the registry and corrupt it. Before doing any experimenting on
a system you care about, you may want to use REGEDIT's export
function to back up the registry.]
If you haven't run REGEDIT before, it
should open to the top level of the registry and look something
like this:
.dmg/Serious Software/Masterapp demo/Doc/graphics/regtop.gif)
The information in the registry is
arranged in a hierarchy, much like a file system, so Microsoft
created a file folder interface to browse it. The information
itself really isn't stored in physical file folders and subfolders
the way the registry depicts it, but it is stored in a tree
structure. The base categories at the very top of the hierarchy
are designed to contain certain types of information.
|
Base category
|
Contains information about ...
|
|
HKEY_CLASSES_ROOT
|
document types, such as what extension identifies them
and what application to open them with
|
|
HKEY_CURRENT_USER
|
the current user's preferences for the system setup
such as program groups, color scheme, network
connections
|
|
HKEY_LOCAL_MACHINE
|
system configuration info not dependent on user like
installed hardware, available keyboard layouts, file
system being used
|
|
HKEY_USERS
|
preference information for all users.
HKEY_CURRENT_USER actually is a convenience category that
just points to a sub-node of this category
|
The other two - HKEY_CURRENT_CONFIG and
HKEY_DYN_DATA are not accessible by MasterApp, so won't be covered
here.
Underneath any base category are many
"keys" and "values". A key is any valid path in the hierarchy. The
content of a key is usually more keys and also some values. Values
contain the data being stored. In the REGEDIT window, the left
pane displays keys and the right pane displays values. Each value
has two parts - the value name, which describes what is stored
there, and the actual value data.
When you double-click on any of the
"folders" in REGEDIT, the path to the current key is displayed at
the bottom of the window, any subkeys display below it as
subfolders and any values for that key display in the right pane.
In the screen shot below, the key is:
My Computer\HKEY_CURRENT_USER\ControlPanel\Appearance
It has a subkey called Schemes. It also
has 3 values, displayed in the right pane - Default, Current, and
CustomColors. One of the values shown is the user's current
desktop scheme. The value name is "Current". The value data is
"Eggplant".
.dmg/Serious Software/Masterapp demo/Doc/graphics/onekey.gif)
Every key has at least one value - the default value. The name
of the value is not really "Default". That's why the parens are
around its name. To specify the default value in any of the
registry methods, use "", an empty string, for the value name.
Registry values can contain several different types of data.
The most common ones are string, integer or bytelist (binary
data). In the screen shot above, the default value and the value
"Current" contain string data while value Custom Colors contains a
byte list. Unless you are an experienced programmer, the entries
you will find most useful will be string or integer entries.
When you want to work with a particular value using the
registry methods, you break the key up into two parts and pass the
value name as the third part. Let's use the key from the screen
shot as an example:
My Computer\HKEY_CURRENT_USER\ControlPanel\Appearance
Base: top-level base category. This can only be
HKEY_CLASSES_ROOT,
HKEY_CURRENT_USER,
HKEY_LOCAL_MACHINE,
HKEY_USERS. Note that there is nowhere to
pass the computer name, even though technically that is part of
the key. You leave off the computer name completely. You also
leave off beginning and trailing slashes. So base for the example
key would be:
HKEY_CURRENT_USER
Key: everything in the key after
the base, again minus beginning or trailing slashes. So key for
the example would be:
ControlPanel\Appearance
Value: the name of the value you
are interested in. For the example key, possible values would
be:
"" (for the default)
Current
CustomColors
Why does it work like this? So that if there is something wrong
with one of the arguments MasterApp can return a more specific
error message about what part is wrong. For instance, if you make
a typo in the base part, MasterApp will return:
Error: no compiled key for the base
That helps you figure out which part of the entry is wrong,
which can be helpful if the entries are very long.
mappGetWindowsRegistry (
baseString, keyString, valueString )
baseString: string top-level base category of
registry key
keyString: string remainder of registry key after base
valueString: string value name within key or "" for default
Returns: data contained by the specified registry entry
or string beginning with "Error:". Data type depends on registry
entry.
Win32-only method. Returns the data for a specific value of the
specified key. Returns a string, an integer, or binary data in the
form of a list of bytes (as integers from 0 to 255), depending on
what type of entry is present in the registry.
Examples:
put mappGetWindowsRegistry("HKEY_CURRENT_USER","ControlPanel\Appearance","Current")
-- "Eggplant"
-- Get the document type name for .htm files
--
put mappGetWindowsRegistry("HKEY_CLASSES_ROOT",".htm","")
-- "htmlfile"
See what browser is registered to handle .htm files
put mappGetWindowsRegistry("HKEY_CLASSES_ROOT","htmlfile\shell\open\command","")
-- ""C:\PROGRA~1\PLUS!\MICROS~1\iexplore.exe" -nohome"
mappSetWindowsRegistry (
baseString, keyString, valueString, dataAnytype )
baseString: string top-level base category of
registry key
keyString: string remainder of registry key after base
valueString: string value name within key or "" for
default
dataAnytype: data value to write to specified key
Returns: "OK" or string beginning with "Error:"
Win32-only method. Sets the data of a registry value. The
value, key, and its parent keys are created if needed. If the
value already exists, its data is overwritten with the data you
supply.
You can supply a string, an integer, or binary data in the form
of a list of bytes as integers from 0 to 255. If the type of data
you supply does not match the current data type for an existing
value, the value's data type will be changed to match the data you
are writing.
Warning: This is a dangerous
method. It can damage your registry data and prevent your
computer from working if you write data unintentionally to the
wrong key. Please back up your registry data before doing
development work and testing by using REGEDIT's export option
(Registry -> Export registry file)
If you are editing an existing value make sure that your data
type matches the existing type by using mappGetWindowsRegistryEntryType.
Check Microsoft doc for the limits before writing extraordinarily
long strings or binary lists. Also, while it is possible to write
data to the "HKEY_USERS" base, it isn't advisable. Edit
HKEY_CURRENT_USER instead. The edited information for the user
will automatically update HKEY_USERS.
Examples:
-- Make a brand new key for a company and create a value for it
mappSetWindowsRegistry("HKEY_CURRENT_USER","Software\updateStage","Install","C\TEMP\USTAGE")
-- Change the current user's screen saver time out to 60 seconds (note that 60 is a string)
mappSetWindowsRegistry("HKEY_CURRENT_USER","Control Panel\desktop","ScreenSaveTimeOut","60")
mappGetWindowsRegistryEntries
( baseString, keyString )
baseString: string top-level base category of
registry key
keyString: string remainder of registry key after base
Returns: string listing subkeys and values available
within specified key or string beginning with "Error:"
Win32-only method. Returns a string with all entries, both
subkeys and value names, available under the specified key; one
entry per line. Subkeys are listed first, then values; but the
order in which subkeys and values are reported may vary from call
to call. Default is not listed because it doesn't really have a
value name.
Example:
put mappGetWindowsRegistryEntries("HKEY_CURRENT_USER","ControlPanel\Appearance")
-- "Schemes
CustomColors
Current"
mappGetWindowsRegistryKeys
( baseString, keyString )
baseString: string top-level base category of
registry key
keyString: string remainder of registry key after base
Returns: string listing only subkeys available within
specified key or string beginning with "Error:"
Win32-only method. Returns a string with just the subkeys
available under the supplied key; one entry per line.
Example:
put mappGetWindowsRegistryKeys("HKEY_CURRENT_USER","ControlPanel\Appearance")
-- "Schemes"
mappGetWindowsRegistryValues
( baseString, keyString )
baseString: string top-level base category of
registry key
keyString: string remainder of registry key after base
Returns: string listing only values of subkeys available
within specified key or string beginning with "Error:"
Win32-only method. Returns a string with just the value names
available within the specified key; one entry per line. Default is
not listed because it doesn't really have a value name.
Example:
put mappGetWindowsRegistryValues("HKEY_CURRENT_USER","ControlPanel\Appearance")
-- "CustomColors
Current"
mappGetWindowsRegistryEntryType
( baseString, keyString, entryString )
baseString: string top-level base category of
registry key
keyString: string remainder of registry key after base
entryString: string value name or subkey name within key or
"" for default
Returns: string describing data type contained by
registry entry or string beginning with "Error:"
Win32-only method. Returns the type of data stored by the
specified entry. Possible types are:
string
integer
bytelist
unsupported
subkey
Example:
put mappGetWindowsRegistryEntryType("HKEY_CURRENT_USER","ControlPanel\Appearance","Current")
-- "string"
mappDeleteWindowsRegistry (
baseString, keyString, valueString )
baseString: string top-level base category of
registry key
keyString: string remainder of registry key after base
valueString: string value name within key or "" to delete
entire key
Returns: "OK" or string beginning with "Error:"
Win32-only method. Erases one value within a key or an entire
registry key. On Windows 95, this also deletes any subkeys. On
Windows NT, this won't work if subkeys exist, so use mappGetWindowsRegistryKeys
to detect and delete any subkeys first. Since "" for value is used
here to delete the entire key you may wonder how you delete the
default value for a key. You can't. All registry entries have to
have a default value.
Example:
-- Delete just the value Install but leave updateStage's key
mappDeleteWindowsRegistry("HKEY_CURRENT_USER","Software\updateStage","Install")
-- Delete the entire updateStage key
mappDeleteWindowsRegistry("HKEY_CURRENT_USER","Software\updateStage","")
Warning: This is a dangerous
method. It can damage your registry data and prevent your
computer from working if you write data unintentionally to the
wrong key. Please back up your registry data before doing
development work and testing by using REGEDIT's export option
(Registry -> Export registry file).
This catchall category contains
methods for finding out about and setting the default printer for
use with mappPrintDocument
and for getting the operating system type.
mappGetDefaultPrinter ()
Returns: string printer name
Win32-only method. Reports the current default printer
name.
Example:
set currPrinter = mappGetDefaultPrinter()
mappSetDefaultPrinter (
printerString )
printerString: string printer name
Returns: "OK" or string beginning with "Error:"
Win32-only method. Selects a new default printer. Requires the
exact results of either mappGetDefaultPrinter
or one of the lines returned by mappGetInstalledPrinters.
Example:
mappSetDefaultPrinter("Epson Stylus COLOR ESC/P 2,ESCP2MS,LPT1:")
mappGetInstalledPrinters
()
Returns: string list of installed printers, one
printer per line
Win32-only method. Returns a list of all of the installed
printer drivers. Since it is possible for a printer driver to
exist on a system that is not really connected to that printer, it
is probably better to present the printer names to the user,
rather than to select one automatically for the user.
Example:
put mappGetInstalledPrinters()
-- "HP DeskJet 500,HPDSKJET,LPT1:
Epson Stylus COLOR ESC/P 2,ESCP2MS,LPT1:
TI microLaser PS17,PSCRIPT,LPT1:"
mappWindowsFlavor ()
Returns: string containing operating system type
Win32-only method. Returns one of the following:
win31
win95
winNT
When MasterApp is running on a Windows 98 system it returns
"win95". You can use the registry reading methods to get more
detailed information about the system.
There is a registry setting that contains a string that reports
what version of Win you are running, on non-NT systems.
set winType = mappGetWindowsRegistry("HKEY_LOCAL_MACHINE","Software\Microsoft\Windows\CurrentVersion\","Version")
put winType
-- "Windows 98"
There is another registry setting that only exists on Windows
NT that contains a string that reports whether you are running on
Windows NT Workstation or Server:
set winntType = mappGetWindowsRegistry("HKEY_LOCAL_MACHINE","SYSTEM\CurrentControlSet\Control\ProductOptions\","ProductType")
put winntType
-- "ServerNT" -- if running NT Server
-- "WinNT" -- if running NT Workstation
Example:
set os = mappWindowsFlavor()
mappDontUseLayerManager
()
Returns: "OK"
Mac-only method. Turns off use of the Mac system Layer
Manager, which is turned on by default if MasterApp detects a
Mac system version of 7.1 through 8.*. On those systems, MasterApp
makes use of Apple's undocumented and unsupported Layer Manager to
retrieve information about windows outside of the Director
projector. Without Layer Manager, MasterApp can only detect and
work with the windows belonging to the Director projector.
If you want to guarantee future compatibility at the expense of
losing features now, you can use this method to turn off the Layer
Manager.
Example:
mappDontUseLayerManager
mappUseLayerManager ()
Returns: "OK"
Mac-only method. Turns on use of the Mac system Layer
Manager, which is already turned on by default if MasterApp
detects a Mac system version of 7.1 through 8.*. On those systems,
MasterApp makes use of Apple's undocumented and unsupported Layer
Manager to retrieve information about windows outside of the
Director projector. Without Layer Manager, MasterApp can only
detect and work with the windows belonging to the Director
projector.
This method is provided for future compatibility. It is not
necessary to use it with current operating system versions since
use of Layer Manager is already turned on by default.
Example:
mappUseLayerManager
mappGetSystemVersion( )
Returns: string containing Mac OS system version
Mac-only method. The mappGetSystemVersion method helps you
determine the MacOS version, which you can use to plan future
behavior of a product. It returns a string that can be turned into
a floating point number with 'float()', for numerical comparisons,
or it can be compared digit by digit. For instance, System 7.6.1
returns the string '07.61'.
Example:
set ver = mappGetSystemVersion( )
set ver = float(ver)
if ver < 9.0 then
-- code specific to System 8.* or below
Encoding for special characters
On the Mac, some applications reuse the space assigned to
empty names in a window list to store binary data. The data can
include commas and control characters like RETURN or even
numToChar(0) which Director understands as end of string. On the
Mac, MasterApp lists a window's controls as "child windows" for
the sake of consistency, but this concept doesn't really exist on
the Mac. Application programmers are not necessarily expecting an
outside app like MasterApp to be retrieving the names of a
window's controls. Similarly, it is also possible for control
characters to be returned within tasknames in a returned task list
or filename.
In order to prevent binary data in a window name field from
truncating the returned window list, MasterApp on both platforms
filters for character 0, and replaces it with the string "{0}" in
the returned data. It also replaces character "{" with the string
"{l}" for "left bracket" and the character "}" with "{r}" for
right bracket, so you can distinguish a left bracket in the
data.
MasterApp is most commonly used to control Acrobat Reader
or a web browser, so those tasks are covered in some depth here.
You will want to check MasterApp's online
tech notes as well, for how-to's and tips covering other
less-traveled technical issues.
Open a web page
You don't need MasterApp to simply open a web page with a
browser. Director's own "goToNetPage" in version 6 or above will
do that for you quite nicely. However, "goToNetPage" opens
whatever browser is designated as the default browser on the
user's system. Things get a little trickier if you want to launch
a specific browser.
Windows
You can use the Windows registry to find the installed path of
the browser you are interested in. The registry is preferable to
using mappLocateExecutable because you can use a registry entry to
find the most recent version if multiple versions are
installed.
Getting the installed path for Netscape is very
straightforward:
put mappGetWindowsRegistry("HKEY_CURRENT_USER",
"Software\Netscape\Netscape Navigator\Main", "Install
Directory")
-- "C:\Program Files\Netscape\Navigator"
For Explorer you have to go through several entries. First look
here to see if Explorer is installed. Any doc path returned for
"Local Page" indicates that Explorer is installed.
put mappGetWindowsRegistry("HKEY_CURRENT_USER",
"Software\Microsoft\Internet Explorer\Main", "Local
Page")
-- "C:\WINDOWS\SYSTEM\blank.htm"
This entry returns the current version, which you will use in a
subsequent call:
put mappGetWindowsRegistry("HKEY_CLASSES_ROOT",
"InternetExplorer.Application\CurVer", "")
-- "InternetExplorer.Application.1"
The current version is used as part of the key for this next
call which returns the ClassID for the app:
put mappGetWindowsRegistry("HKEY_CLASSES_ROOT",
"InternetExplorer.Application.1\CLSID", "")
-- "{0002DF01-0000-0000-C000-000000000046}"
Finally, you use the ClassID as part of the key that
returns the path to IE:
put mappGetWindowsRegistry("HKEY_CLASSES_ROOT",
"CLSID\{0002DF01-0000-0000-C000-000000000046}\LocalServer32",
"")
-- ""C:\PROGRA~1\PLUS!\MICROS~1\iexplore.exe""
Current versions of both Netscape and Explorer will accept a
URL as the command line argument. If the user had set up the
browser to allow auto-connect the browser will initiate a
connection after launch. You would supply mappLaunch with the file
path obtained from the registry and the URL like so:
mappLaunch("C:\PROGRA~1\PLUS!\MICROS~1\iexplore.exe",
"http://www.updatestage.com")
Mac
On the Mac there is no registry for looking up the path to the
browser, and browsers don't recognize a URL passed as a
command-line argument. Since the Mac links documents to apps by
their type and creator, on the Mac you must create an HTML
document with the type and creator that matches the browser you
want to open. Inside the document you can include a META-REFRESH
tag, which instructs the browser to open a URL.
Setting the type and creator for the document
You must use a file resource editor like Apple's ResEdit
or Peter van der Heide's Drop
It to set the HTML file's type and creator for either Netscape
Navigator or Internet Explorer. They are as follows:
|
Browser
|
Type
|
Creator
|
|
Netscape Navigator
|
TEXT
|
MOSS
|
|
Internet Explorer
|
TEXT
|
MSIE
|
If you don't have access to a resource editor you can copy an
existing HTML document that shows either the Netscape Navigator or
Explorer icon, delete all of the text, and paste in your own HTML.
The document will still retain the correct type and creator. For
Netscape Navigator you can use bookmarks.html. Any of the help
files that come with Explorer will do.
It's possible that the user will only have one browser
installed. On the PC that's not a problem since only one app will
be registered to handle HTML files. On the Mac, if you open a HTML
file with a Type and Creator for Netscape Navigator, only Netscape
Navigator will be searched for and launched. Since MasterApp
returns an error message if it can't find the app, you can look
for one browser, check for an error, then look for the other if
necessary.
Automatically opening a URL
Both Netscape Navigator and Internet Explorer support a
Netscape HTML tag called META-REFRESH
to automatically open a URL when the HTML document is opened. Here
is a bare-bones HTML example:
.dmg/Serious Software/Masterapp demo/Doc/graphics/meta.gif)
Another way to open up a URL directly is to create an HTML file
in bookmark format. If you open a bookmark file, the browser will
navigate directly to the bookmark's URL. Unfortunately the
bookmark file format differs between the two browsers and differs
depending on platform so you have to have a separate bookmark file
for each browser and platform.
On the Mac, you create plain text bookmark files with a
particular type and creator and a URL on the first line of the
file. Set the type and creator with a resource editor or copy a
bookmark file from either browser and substitute your own URL. The
type and creator for bookmark files are listed in the table
below:
|
Browser
|
Type
|
Creator
|
|
Netscape Navigator
|
URL
|
MOSS
|
|
Internet Explorer
|
LINK
|
MSIE
|
For Navigator the file should contain a URL and nothing
else:
http://www.updatestage.com
For Internet Explorer there should also be just one line
containing the URL but it should be formatted like so:
[Internet
Shortcut]/r/nURL=http://www.updatestage.com/index.html
Bookmarks on Windows
Modern Win browsers can open a URL passed to them as a
command-line argument, but you can also open a URL by passing a
bookmark type file.
On the PC under Win32, a bookmark is a shortcut file - not a
plain text file. You can create a new one pointing to your URL by
modifying an existing file. Shortcut filenames end in .URL. Search
for one of those in the Netscape History folder or the Explorer
Favorites folder and modify the Target URL property. Treat the
shortcut as a document:
mappOpenDocument("C:\SHORTC.URL")
Check for
existence of an app and launch an installer
You can combine mappLocateExecutable
and mappLaunch to determine whether
software has already been installed that will handle a particular
document type and launch an installer if it has not. The example
behavior below illustrates how to look for an application using a
document and how to wait for a running installer to finish by
monitoring the taskList.
A looping exitFrame handler checks the taskList on every frame
to see if the installer task is still running. The looping frame
allows external tasks some processing time. The usual way to wait,
by using a Director repeat loop, would prevent the very task you
are waiting for, from running.
-- Installer
--
-- Looks for a program name. If program is not already installed, runs
-- an installer, then launches the program.
--
-- Usage
--
-- Place behavior on a frame. Will loop on the frame until the program
-- has been launched or until the program has been installed and
-- launched or until there has been an error. Requires a field to
-- write progress messages to. Field does not have to be on screen.
--
-- Behavior Dialog Fields
--
-- Path to doc relative to this movie: Path to doc
-- includes doc name. Is relative to moviepath.
--
-- EX: FOLDER\HELP.DOC
--
-- If movie is in C:\TEMP, docpath would be
-- C:\TEMP\FOLDER\HELP.DOC
--
-- Path to installer relative to this movie: Path to installer
-- includes installer name. Is relative to moviepath.
--
-- EX: FOLDER\INSTALL.EXE
--
-- If movie is in C:\TEMP, would launch installer at
-- C:\TEMP\FOLDER\INSTALL.EXE
--
-- Name of field to write status information to: name of field
-- that will display progress messages
--
property docPath,installerPath,statusField
property progressFlag,installerID,initialWait
-- docPath: path to doc relative to this movie associated with
-- app to locate on hard drive
-- installerPath: path to installer relative to this movie
-- statusField: name of field containing status info
-- progressFlag: symbol tracking what the state of the install is
-- installerID: taskID of install program while it is running
-- initialWait: 3 second delay that allows installer to be fully
-- launched before looking for it on task list
on beginSprite
set progressFlag = #start
put "" into field statusField
end
on exitFrame
case progressFlag of
#start: lookForProgram
#install: installProgram
#wait: waitForInstaller
#installOver: lookForProgram
#done: go the frame + 1
end case
go the frame
end
on lookForProgram
-- Looks for program on user's hard drive
-- Either launches it or sets a flag to start install
--
set docPath = the moviePath & docPath
set programPath = mappLocateExecutable(docPath)
if char 1 to 5 of programPath = "Error" then
if progressFlag <> #installOver then
set progressFlag = #install
put "Did not find program" into field statusField
else
set progressFlag = #done
put RETURN & "Still did not find program after install" after field statusField
end if
else
set err = mappLaunch(programPath,"")
if stringP(err) or (the machineType <> 256 and (err < 0)) then
set progressFlag = #install
put "Cannot launch program" into field statusField
else
set progressFlag = #done
put "Successfully launched program" into field statusField
end if
end if
end
on installProgram
-- Launches install program
--
set installerPath = the moviePath & installerPath
set err = mappLaunch(installerPath,"")
if stringP(err) or (the machineType <> 256 and (err < 0)) then
set progressFlag = #done
put RETURN & "Cannot launch installer" after field statusField
else
set installerID = " " & err & " "
set progressFlag = #wait
set initialWait = the ticks + 180
put RETURN & "Waiting for installer to finish" after field statusField
end if
end
on waitForInstaller
-- After initial 3 second wait, keeps
-- checking task list waiting for installer's task ID
-- to disappear
--
if the ticks < initialWait then
exit
else
set allTasks = " " & mappGetTaskIDs() & " "
if not (allTasks contains installerID) then
set progressFlag = #installOver
put RETURN & "Installer has finished" after field statusField
end if
end if
end
on getPropertyDescriptionList
set p_list = [:]
set temp = [:]
addProp temp,#comment,"Path to document relative to this movie:"
addProp temp,#format,#string
addProp temp,#default,"DOCS\HELP.DOC"
addProp p_list,#docPath,duplicate(temp)
set temp = [:]
addProp temp,#comment,"Path to installer relative to this movie:"
addProp temp,#format,#string
addProp temp,#default,"INSTALL\SOMEPROG.EXE"
addProp p_list,#installerPath,duplicate(temp)
set temp = [:]
addProp temp,#comment,"Name of field to write status information to:"
addProp temp,#format,#string
addProp temp,#default,"Launch status"
addProp p_list,#statusField,duplicate(temp)
return p_list
end
Go to a specific Acrobat page
There isn't any way to open an Acrobat document to a
particular page by sending a command line argument with the open,
but you can still navigate to the page by typing the page number
into the "Go Page" dialog using simulated input. The following
behavior demonstrates how you can combine window operations and
simulated input operations to target a window for keystrokes and
mouse clicks.
The window remains visible while this is going on. You can
experiment with the built-in waits to close it more quickly, or
you can try moving it off screen. Sending simulated input to the
dialog while it is off screen would require more development on
Win because the dialog widgets do not respond to input in the same
way when the dialog is not visible.
-- Type into Acrobat page number dialog
--
-- Uses simulated user input to type a page number into
-- Acrobat's "Go Page" dialog and go to that page in
-- the document
--
-- Usage
--
-- Place behavior on a button. Requires a field to
-- get the page number from. Field does not have to be on screen.
--
property pageField,plat
-- pageField: name of field to get page number from
-- plat: "Mac" or "Win"
on mouseUp
getPlatform
set num = field pageField
if num = "" then exit
set taskID = findAcroTask()
if taskID = 0 then exit
openPageDialog(taskID)
set dialogID = findDialogWindow(taskID)
if dialogID = 0 then exit
set editFieldID = findEditWindow(taskID,dialogID)
if editFieldID = 0 then exit
sendPageToWindow(editFieldID,dialogID)
end
on getPlatform
if item 1 of the platform = "Macintosh" then
set plat = "Mac"
else
set plat = "Win"
end if
end
on openPageDialog taskID
if plat = "Win" then
-- Send keyboard shortcut for page dialog.
-- Must find main window and activate menu
-- first on Win
--
set wins = mappGetTaskWindowIDs(taskID)
set mainWin = findWindowNamed("Acrobat Reader",wins,FALSE)
mappWindowToFront(mainWin)
mappShowMenu(mainWin)
feedProcess(15)
mappFakeCharacter(mainWin,"V")
feedProcess(15)
mappFakeCharacter(mainWin,"G")
feedProcess(15)
else
-- Can send keyboard shortcut to any win on Mac
set anyWindow = value(word 1 of mappGetTaskWindowIDs(taskID))
if anyWindow <> 0 then
mappWindowToFront(anyWindow)
-- Cmd-5 Mac menu command to open page dialog
mappFakeCharCode(anyWindow,5941,1)
feedProcess(30)
end if
end if
end
on findDialogWindow taskID
-- Return the window ID of the "Go Page" dialog window
set dialogWin = 0
set wins = mappGetTaskWindowIDs(taskID)
set dialogWin = findWindowNamed("Go To Page",wins,TRUE)
return dialogWin
end
on findEditWindow taskID,dialogWin
-- Return the windowID of the window that will
-- accept the page number typed in with
-- simulated input
--
set pageWin = 0
set savDelim = the itemDelimiter
set the itemDelimiter = ","
if plat = "Win" then
-- On Win the edit field is a child window of
-- the "Go to page" dialog with a type of "Edit"
--
set wins = mappGetChildWindowList(dialogWin)
set lns = the number of lines of wins
repeat with x = 1 to lns
set thisWin = line x of wins
if item 1 of thisWin = "" then
set type = item 5 of thisWin
if type = "Edit" then
set pageWin = value(item 2 of thisWin)
end if
end if
end repeat
else
-- On Mac the edit field is a window with no name and
-- horizontal location of 0
--
set wins = mappGetTaskWindowList(taskID)
set lns = the number of lines of wins
repeat with x = 1 to lns
set thisWin = line x of wins
if item 1 of thisWin = "" then
set id = value(item 2 of thisWin)
if id <> 0 then
if word 1 of mappGetWindowOutsideRect(id) = "0" then
set pageWin = id
end if
end if
end if
end repeat
end if
set the itemDelimiter = savDelim
return pageWin
end
on sendPageToWindow editID,dialogID
-- Read page number from page field and type into
-- dialog's editable field receiving page #
--
set chars = the number of chars of field pageField
mappWindowToFront(editID)
repeat with x = 1 to chars
mappFakeCharacter(editID,char x of field pageField)
feedProcess(30)
end repeat
if plat = "Win" then
-- Find the OK button and send a fake keypress
-- because sending "Enter" to dismiss dialog
-- doesn't work on Win
--
set wins = mappGetChildWindowIDs(dialogID)
set OKwin = findWindowNamed("OK",wins,TRUE)
if OKwin <> 0 then
mappWindowToFront(OKwin)
feedProcess(30)
set winrect = mappGetWindowOutsideRect(OKWin)
-- point 10 pixels inside win
set clickH = value(word 1 of winrect) + 10
set clickV = value(word 2 of winrect) + 10
mappFakeMouseClick(OKwin,clickH,clickV)
feedProcess(30)
end if
else
-- Send RETURN to edit field to dismiss dialog
mappFakeCharCode(editID,9229,0)
feedProcess(30)
end if
end
on findAcroTask
-- Return taskID for Acrobat Reader task
set taskID = 0
if plat = "Win" then
set taskName = "ACRORD"
else
set taskName = "Acroba"
end if
set tasks = mappGetTaskList()
set lns = the number of lines of tasks
repeat with x = 1 to lns
set thisTask = line x of tasks
if char 1 to 6 of thisTask = taskName then
set taskID = value(item 2 of thisTask)
exit repeat
end if
end repeat
return taskID
end
on findWindowNamed windowName,idList,exact
-- Return a window with a name that matches requested name
--
-- windowName: name string to look for
-- idList: string containing list of window ids
-- exact: TRUE if match on name should be exact, FALSE if name
-- can contain string you are looking for
--
set windowID = 0
set ids = the number of words of idList
repeat with x = 1 to ids
set thisID = value(word x of idList)
set curName = mappGetWindowName(thisID)
if curName = windowName or (curName contains windowName and exact = FALSE)then
set windowID = thisID
exit repeat
end if
end repeat
return windowID
end
on feedProcess someTicks
-- Feed timeslices for duration in ticks of someTicks
set doneTime = the ticks + someTicks
repeat while the ticks < doneTime
mappFeedGenericTimeSlice()
end repeat
end
on getPropertyDescriptionList
set p_list = [:]
set temp = [:]
addProp temp,#comment,"Name of field containing page number:"
addProp temp,#format,#string
addProp temp,#default,"PageNumber"
addProp p_list,#pageField,duplicate(temp)
return p_list
end
Limitations
Mac Layer Manager
MasterApp methods that operate on or get information about
windows depend on a system component called the Layer Manager. The
Layer Manager was described in a preliminary document for Mac
developers attending a prerelease version of System 7.1, but Apple
later decided not to officially support or document the API.
MasterApp Mac was coded using the Layer Manager because it was,
and still is, at the time of this writing, the only way for
MasterApp to monitor and address windows outside of the Director
application itself.
Although Mac system versions have continued to support Layer
Manager, it is possible that a future Mac operating system will
not support Layer Manager. If, at that time, there is still no
equivalent replacement, the MasterApp methods that rely on Layer
Manager will not be able to return as much information.
The following MasterApp methods rely on the Layer Manager on
the Mac. This is not an issue for the PC versions of
MasterApp.
|
Method group
|
Without Layer Manager these methods will
...
|
mappGetTaskWindowList()
mappGetTaskWindowIDs()
mappParentWindowTopChild()
mappGetWindowTask()
mappWindowName()
mappGetWindowName()
mappSetWindowName()
mappWindowIsVisible()
mappWindowExists()
mappWindowHasChildren()
mappCloseWindow()
mappShowWindow()
mappHideWindow()
mappWindowType
mappGetWindowType()
mappGetWindowOutsideRect()
mappGetWindowInsideRect()
mappSetWindowOutideRect()
mappSetWindowRect()
mappMaximizeWindow()
mappMinimizeWindow()
mappRestoreWindow()
mappWindowParent()
mappGetWindowParent()
mappGetChildWindowList()
mappGetChildWindowIDs()
mappWindowToFront()
mappWindowToBack()
mappChildWindowAtPoint()
|
only return information for the Director or Authorware
task
|
mappGetParentWindowList()
mappGetParentWindowIDs()
|
only return window ID's owned by the Director or
Authorware task. Will return the frontmost window
first.
|
mappGetTaskOrder()
|
not return the`task list in front to back order,
although it will always return the frontmost app first.
Also may include invisible system apps like File Sharing
which would not normally be included if Layer Manager was
enabled.
|
mappGetDesktopWindow()
|
return 0. However, when 0 is supplied to
mappGetWindowInsideRect() or mappGetWindowOutsideRect()
in this situation, the desktop rectangle is nonetheless
returned accurately. This is due to some special code
that was designed to make the Mac side behave the same
way as the Windows side. This dates from when
desktopRectList wasn't a Lingo keyword yet and this was a
way to find out the screen size, not the stage window
size.
|
mappAnyWindowAtPoint()
|
not return a windowID for a window that does not
belong to the host app, even though it may be under the
supplied point.
|
mappFakeMouseClick()
mappFakeMouseClickWait()
mappFakeMouseDrag()
mappFakeCharacter()
mappFakeCharacterWait()
mappFakeCharCode()
mappFakeCharCodeWait()
|
will work, but will not switch to the task that owns
the supplied windowID automatically before simulating
input
|
Acrobat path
Some applications which register themselves to open documents
may not properly report their installed location to Windows
itself. This manifests itself in a failure of mappLocateExecutable
to report the installed location.
One workaround is to use mappOpenDocument
which may work correctly even though mappLocateExecutable isn't
returning the correct results. However, there may be times when
you really do want to know the true full file name of the
application.
Fortunately, there is a workaround using mappGetWindowsRegistry.
Here's the way to get an app from a document type.
put mappGetWindowsRegistry("HKEY_CLASSES_ROOT", ".pdf", "")
-- "AcroExch.Document"
This string would be a string with word 1 'Error:' if nothing
has been installed to handle .pdf files. Otherwise, this returns
the document type to use for a second lookup to get the
application registered to open the document.
put mappGetWindowsRegistry("HKEY_CLASSES_ROOT",
"AcroExch.Document\Shell\Open\Command", "")
-- "c:\Program Files\Acrobat\AcroRd32.exe "%1""
The \Shell\Open\Command portion is standard; any document that
opens an app when you double click on it should have an entry in
that format. Windows itself sets up these registry entries, even
for 16-bit apps that don't themselves access the registry when
they are installed.
Note the '%1' at the end, which indicates the place to
substitute a file to open. Note that it's between QUOTE
characters, which is so that a document file using a long file
name containing a space will be interpreted as one argument, not
two arguments. Not all applications surround the '%1' with QUOTE
characters; Acrobat does, but most 16-bit applications don't
because they aren't aware of the long file name additions to
Windows 95/NT. Some programs also include '%2', '%3', %4' etc. in
this registry entry. These are used to indicate more than one file
to open at a time. Some applications also surround the application
name itself with QUOTE characters; Acrobat doesn't.
To be robust and handle all variations of quote marking with
this registry entry, you should check for '%1' in a returned
string; snip any preceding quote if present; snip the %1 itself
and anything that follows it; snip any preceding spaces; and check
the remainder, for a starting and ending quote mark, snipping them
if present. That should leave you with just the application name.
Quotes and % characters are not allowed in long file names or
folder names themselves; therefore, this should be a reliable
technique for resolving a document type into an application file
name, without knowing the application itself at authoring
time.
Palettes
If you're working in 8-bit color and you open an external app
with a palette that's not the same as the one you're using in
Director - especially if that app opens up dialog boxes, Director
might never realize its correct palette again. This has
NOTHING TO DO WITH MASTERAPP other
than you might have used MasterApp to launch the external app.
But, some remedies are:
1. Use the Windows palette for the Director movie
2. Make sure the projector is set to "Animate in background"
and the movie is set to "Remap colors when needed"
3. If those 2 suggestions still don't do it, make a copy of
DIRECTOR.INI, rename it with your projector's name.INI and edit it
as follows. The [Palette] line must be UNcommented:
[Palette]
Animation = 0
Place MYPROJECTOR.INI next to your projector for distribution.
Use this as a last resort because it slows down other palette ops
in Director.
PowerPoint
According to customer reports, neither the Xtra nor XObject
version of MasterApp is able to work seamlessly to simulate input
in PowerPoint, due to the way PowerPoint appears to be coded. One
option for Director developers who wish to work with PowerPoint
content is Macromedia's Xtra for converting PowerPoint
presentations into Director movies.
Simulated input
PowerPoint does not respond to all simulated input, especially
in dialog boxes.
Background and minimized modes
PowerPoint shows don't support background or minimized modes,
and once a PowerPoint show is invoked, either through its viewer
using the .ppt format or through the full application using .pps,
it puts up a black screen for a long time while it slowly
loads.
Sending Cmd-Q from Director 7 projectors
On Macintosh platforms, in a Director 7 projector, when you
send the Cmd-Q keystroke to another application's window like
this:
mappFakeCharCode ( windowID, 3185, 1 )
the other application will quit, but sometimes the currently
running handler in the Director projector will abort too. This is
only a problem in D7 projectors. The workaround is to use
mappRudeQuitTask instead, which is
actually only "rude" on Windows platforms.
Volume named "Error"
On the Mac, if you have a volume named "Error" the following
methods could conceivably return a valid path that started with
the string "Error:", confusing error checking code that expected
that string to signal an error:
mappLocateExecutable
mappModuleFileName
mappHostAppFileName
mappDirectorFileName
mappAuthorwareFileName
Version history
Current Version
Mac Xtra: v1.04
Win 32-bit Xtra: v1.0.4
Mac
Xtra
v1.04 released 3/22/99
- Added code to many methods that return a string, that
encodes control characters to keep them
from truncating the returned window or task list.
- Error checking was added to many methods that accept a
windowID to prevent them from passing a 0 or other bogus windowID
passed in to them, back out to the operating system, which can
cause a system crash.
- Added method mappAuthorwarePresentationWindow
- mappGetParentWindowList
and mappGetParentWindowIDs
will now return windowIDs in front to back task order on Mac. This
was previously only true on Win.
- mappGetTaskIDs now returns the
frontmost task's taskID first on Mac
- mappGetDesktopWindow has
been modified to prevent an unusual error condition where an open
folder on a disk named "Desktop" might be misidentified as the
full desktop window.
v1.03 beta released 2/4/99
Converted Mac XObject to Xtra format. Added Mac-only
methods mappFixMenuBarOnLaunch,
mappDontFixMenuBarOnLaunch,
mappFixMenuBarHeight
XObject
v1.02 released 2/9/98
Documentation changed to reflect new publisher,
updateStage. The licensed version's serial number registration
technique was simplified and made compatible with Windows XObject
and Xtra serial numbers.
v1.01 released 8/1/97
- Changed the default state for Use Layer Manager MasterApp
property to TRUE
- Added mGetSystemVersion()
v1.0 released 3/29/97
Added methods (and changed defaults) to keep the
mappLocateExecutable method from locating alias files instead of
application files, when asked to locate an application by file
name
v0.50 released 2/28/97
- Renamed to MasterApp from ZapApp.
- mOpenDocument and mPrintDocument now report instanceIDs, or
error codes if they fail.
- Extended expiration date to 4/1/97.
- Enabled mCloseWindow, mSetCloseBoxOffset, and
mFindWindowPart.
- Finished implementation of alternate usage of
mappLocateExecutable, which now allows you to search for an
arbitrary file name on all disks, rather than only specifying a
full path to a document file with a particular application's
creator signatures.
- Added mLaunch and mLaunchButDontActivate
- Added mWindowExists, mWindowToBack, mShowWindow, mHideWindow,
mFakeCharacter, mAnyWindowAtPoint, mChildWindowAtPoint.
- Added Mac-only mGetTaskOrder method
v0.49c released 1/10/97
- mTaskName method changed to report the same format task names
as mGetTaskList for desk accessories
- Fixed bug where mOpenDocument and mLocateExecutable would try
to launch or report the location of a previously installed but
later deleted application.
v0.49b released 12/17/96
- Added mGetMenuBarHeight, mSetMenuBarHeight, mGetSystemScript,
mGetSystemRegion
- Fixed problem with mWindowToFront, mOpenDocument,
mPrintDocument, etc. where they only brought windows frontmost
within their own task
- Restricted the use of mSetActiveWindow to Director's own
windows
- Extended expiration date to 2/1/97.
v0.49 released 12/7/96
- Added many new methods for getting window information,
printing documents, and simulating mouse and keyboard input.
- Added code to prevent ill-behaved applications from causing
MasterApp to fail when searching their windows.
v0.41 beta released 11/15/96
Releasable, non-datekilled version. Fixed bug where
mGetTaskName and mGetTaskID would cut off the last character of
their returned strings
v0.40 beta released 11/8/96
Initial Mac release ported from Windows MasterApp .
Win 32-bit Xtra
v1.04 released 3/22/99
- Added code to many methods that return a string that encodes
control characters to keep them from truncating the returned
window or task list. This is much more likely to occur on the Mac,
but this was added to Win side to make cross-platform coding
consistent
- Added method mappAuthorwarePresentationWindow
v1.0.0.37 released 4/22/98
Added the methods missing from the Xtra that were
previously only available in the XObject.
v1.0.0.20 beta released 2/9/98
- Added do-nothing implementations for all methods.
- Implemented most simulated input methods and window
size/position methods.
- First release published by updateStage.
v1.0.0.12 beta released 9/11/97
- Fixed crash bug in mappGetTaskWindowList() when the taskID
passed as an argument used more than one thread, but some threads
of which did not own any windows.
- Changed mappWindowToFront() to use a new Win32-only API call,
resulting in better performance of the foreground application
v1.0.0.8 beta released 8/25/97
- Most window control, launch, print and open methods now
implemented.
- Some methods were rewritten to also support Authorware as well
as Director.
v1.0.0.5 beta released 4/10/97
First preliminary development release.
- Supports mLaunch and mappLocateExecutable.
- There are now demo and registered versions available.
- mappGetInstalledPrinters() now successfully returns all
installed printers. The previous version could sometimes omit the
last printer.
- mappSetDefaultPrinter() now verifies that a valid printer is
being requested, which prevents crashes when the developer
supplies an incorrect value for the printer.
v1.0.0.1 beta released 4/3/97
Diagnostic version used in investigating a client bug
report. Supported only the Windows registry method and printer
selection methods.
Standard legal
disclaimer
This software is provided "as is", without warranty of
any kind, either expressed or implied, including, but not limited
to, the implied warranties of merchantability or fitness for a
particular purpose. The software or its documentation or samples
may include errors or technical inaccuracies. Changes are
periodically made to this software, its documentation and samples,
and may be incorporated in new versions. Dirigo Multimedia and
updateStage may improve or change their products at any time
without notice. Neither Dirigo Multimedia nor updateStage assume
responsibility for, and disclaim all liability for, errors in this
software or its documentation and samples. Neither Dirigo
Multimedia not updateStage will be responsible for any damages of
any sort under any conditions. While the software contains no
known bugs, use it at your own risk. As always, you should make
frequent backups of important information.
Some jurisdictions do not allow the exclusion of implied
warranties, so the above exclusion may not apply to you.
Copyright © 1999, updateStage. All rights
reserved.